Skip to main content

Repository customization

Skills (formerly microagents)​

Skills allow you to extend Faheem Code prompts with information specific to your project and define how Faheem Code should function. See Skills Overview for more information.

Setup script​

You can add a .faheem-code/setup.sh file, which will run every time Faheem Code begins working with your repository. This is an ideal location for installing dependencies, setting environment variables, and performing other setup tasks.

For example:

#!/bin/bash
export MY_ENV_VAR="my value"
sudo apt-get update
sudo apt-get install -y lsof
cd frontend && npm install ; cd ..

Hooks​

You can add a .faheem-code/hooks.json file to run custom shell scripts at key moments during agent execution — such as blocking dangerous commands, enforcing linting before the agent finishes, or logging tool usage.

See the dedicated Hooks page for the full guide.

Repository-specific stop hooks​

For repository-specific quality gates, use a Stop hook in .faheem-code/hooks.json. Stop hooks run when Faheem Code tries to finish a task and can block completion until formatting, linting, tests, or other repo-specific checks pass. They work across current agent-server-backed Faheem Code flows.

For example, create .faheem-code/hooks/quality_gate.sh:

#!/bin/bash
cd "${FAHEEMCODE_PROJECT_DIR:-$PWD}"

# Replace this with your repo's checks, such as npm run lint, pytest, or make test.
if ! make test 2>&1; then
  echo '{"decision":"deny","reason":"Quality checks failed. Fix them before finishing."}'
  exit 2
fi

exit 0

Then register it in .faheem-code/hooks.json:

{
  "stop": [
    {
      "matcher": "*",
      "hooks": [
        { "command": ".faheem-code/hooks/quality_gate.sh", "timeout": 120 }
      ]
    }
  ]
}

If you currently use .faheem-code/pre-commit.sh, migrate those checks to Stop hooks when you want quality gates to apply to current agent-server-backed Faheem Code flows. Move the check commands into a Stop hook script like the one above. See the Hooks guide for complete behavior and JSON response details.