My AI Agent Setup (October 2026)
Contents
Contents
TL;DR
- This is the copyable config behind How I Work with AI Agents: hooks, settings, scripts and commands, dated on purpose with tool versions, because agent tools change monthly.
- Auto-compact is off since handoffs replace compaction, and a
PreToolUsehook rewrites every shell command through rtk so the agent gets compressed output without having to remember it (2.2M tokens kept out of the context window, 56.4%, in the count below). - Search picks the tool by the question:
rgfor strings,ast-grepfor syntax shapes, CodeGraph for a symbol’s source, callers and blast radius,jqfor JSON fields. The rule is written inCLAUDE.md, so nobody has to remember it. - The rest of the setup: Matt Pocock’s skills by stage, herdr commands for orchestrating agents and their five states, a narrow allowlist per worktree, version-specific gotchas, and a setup checklist I estimate at under an hour.
This is the config behind How I Work with AI Agents. That post explains the habits and why they exist. This one is the copyable part: hooks, settings, scripts and commands.
It’s dated on purpose. Agent tools change monthly, so treat every flag below as true for these versions and check the project’s docs before you copy:
| Tool | Version |
|---|---|
| Claude Code | 2.1.288 |
| herdr | 0.8.2 |
| rtk | 0.46.0 |
| CodeGraph | 1.6.0 |
| ast-grep | 0.45.3 |
Auto-compact off
Handoffs replace compaction (see the handoff loop), so auto-compact is off in ~/.claude/settings.json:
{
"autoCompactEnabled": false
}
rtk: filter shell output
rtk is a CLI proxy that compresses the output of common commands (git, grep, ls, test runners) before the agent sees it. A PreToolUse hook rewrites every shell command through it, so the agent never has to remember to use it:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "rtk hook claude" }]
}
]
}
}
rtk gain reports what it saved. On 26 September 2026:
Total commands: 8361
Input tokens: 3.9M
Output tokens: 1.7M
Tokens saved: 2.2M (56.4%)
rtk proxy <cmd> runs a command unfiltered. You’ll need it: see the gotchas.
Search: pick the tool by what you’re looking for
Grepping for a function name and then reading five files is the most expensive way to find code. Each question has a cheaper tool:
| Looking for | Tool |
|---|---|
| Strings, comments, flag names, error messages | rg (ripgrep) |
| A syntax shape: a call, a def, an argument pattern | ast-grep |
| A symbol you can name, with callers and blast radius | CodeGraph |
| Fields in JSON output | jq |
# Every call of apply_filter, whatever its arguments
$ ast-grep run -p 'apply_filter($$$ARGS)' -l python src/
# A symbol's source, its callers and what breaks if it changes, in one call
$ codegraph explore "apply_filter"
# Only the fields you need from an API response
$ gh issue list --json number,title,labels --jq '.[] | {number, title}'
CodeGraph keeps a pre-built symbol and call graph of the repo. It runs as an MCP tool and as a UserPromptSubmit hook that attaches relevant code to each prompt:
{
"hooks": {
"UserPromptSubmit": [
{ "hooks": [{ "type": "command", "command": "codegraph prompt-hook" }] }
]
}
}
The rule that makes these tools stick is written in the global CLAUDE.md, not remembered:
In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the
repo root), reach for it BEFORE grep/find or reading files.
If there is no `.codegraph/` directory, skip CodeGraph entirely.
Concise output style
Claude Code has a built-in Concise output style: lead with the result, no preamble, no recap. I set it once, globally:
{
"outputStyle": "Concise"
}
The statusline
The statusline is a script that receives the session as JSON on stdin and prints a line. Mine shows the model, a context bar, and the 5-hour and weekly usage:
Opus (high) | 61k ▓▓▓░░░░░░░ 200k (30%)
🌿 main | window 5h 42% (2h13m) · week 18%
{
"statusLine": { "type": "command", "command": "bash ~/.claude/statusline.sh" }
}
The core of the script, trimmed:
#!/bin/bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name // "Claude"')
effort=$(echo "$input" | jq -r '.effort.level // empty')
# Context bar: tokens in the window vs its size
size=$(echo "$input" | jq -r '.context_window.context_window_size // 200000')
used=$(echo "$input" | jq -r '.context_window.total_input_tokens // 0')
pct=$(( used * 100 / size ))
bar=""
for i in $(seq 1 10); do
if [ $(( i * 10 )) -le "$pct" ]; then bar+="▓"; else bar+="░"; fi
done
# Plan usage windows
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty | round')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // 0 | round')
printf '%s%s | %dk %s %dk (%d%%)\n' "$model" "${effort:+ ($effort)}" $((used / 1000)) "$bar" $((size / 1000)) "$pct"
if [ -n "$five" ]; then printf 'window 5h %d%% · week %d%%\n' "$five" "$week"; fi
The full version adds colours (green, yellow at 50%, orange at 70%, red at 90%), a reset countdown and the git branch. The colours don’t mark 30%. I watch the number.
Matt Pocock’s skills
The skills I use from Matt Pocock’s set, by stage:
| Stage | Skill | What it does |
|---|---|---|
| Setup | setup-matt-pocock-skills | Wires the repo to its tracker, labels and docs layout |
| Think | grill-with-docs | Interviews you about a plan and writes ADRs and glossary terms as it goes |
| Specify | to-spec, to-tickets | Turns the conversation into a spec, then into tickets with blocking edges |
| Plan big work | wayfinder | A map issue with decision tickets, for work bigger than one session |
| Route | triage | Moves issues through triage labels and writes agent-ready briefs |
| Build | tdd, diagnosing-bugs | Red-green-refactor; a diagnosis loop for hard bugs |
| Check | code-review | Reviews the diff against the repo’s standards and against the spec |
| Look things up | research | Checks primary sources and writes the findings to a file in the repo |
| Name things | domain-modeling | Keeps CONTEXT.md and the ADRs in sync with the code’s vocabulary |
| Stop | handoff | Compacts the session into a document for the next session |
/plugin install mattpocock-skills@claude-plugins-official
herdr: the orchestrator’s commands
herdr organises terminals into workspaces (herdr’s sidebar calls them spaces), each with tabs, each split into panes. Every CLI call returns JSON, so the agent reads IDs from the response instead of guessing them:
# A workspace for the task, without stealing my focus
pane=$(herdr workspace create --label fix-314 --cwd ~/work/api-fix-314 --no-focus \
| jq -r '.result.root_pane.pane_id')
# A named worker in it. Arguments after -- go to the agent CLI.
herdr agent start fix-314 --kind claude --pane "$pane" -- --model sonnet
# The brief, then block until the worker is idle, done or blocked
herdr agent prompt fix-314 "$(cat briefs/fix-314.md)" --wait --timeout 1800000
# What happened
herdr agent get fix-314 | jq -r '.result.agent.agent_status'
herdr agent read fix-314 --source recent-unwrapped --lines 120
herdr reports one of five states per agent:
| State | Meaning | What the orchestrator does |
|---|---|---|
working | Busy on a turn | Leaves it alone |
idle | Ready for input, and I’ve seen it | Reviews, then gives it the next task |
done | Finished while nobody was looking | Same as idle |
blocked | Waiting at an approval or a question | Brings it to me |
unknown | herdr can’t classify it | Reads the pane before assuming anything |
agent prompt --wait refuses to type into a blocked agent, so a brief can’t accidentally answer somebody else’s approval dialog.
Clearing has one catch. /clear never puts the agent into working, so agent prompt t1 "/clear" --wait fails with agent_prompt_stalled even though the clear worked. Send it without --wait and check the result:
herdr agent prompt t1 "/clear"
herdr agent read t1 --source visible | tail -3 # the context counter is back to 0
A narrow allowlist per worktree
A new worktree has no saved permission answers, so each worker gets a short allowlist in its .claude/settings.local.json: read-only commands, the test command and git diff. Prompts show the command after the rtk rewrite, so both forms are listed:
{
"permissions": {
"allow": [
"Bash(rtk ls *)", "Bash(rtk find *)", "Bash(rtk read *)", "Bash(rtk grep *)",
"Bash(ls *)", "Bash(find *)",
"Bash(uv run pytest*)", "Bash(rtk uv run pytest*)",
"Bash(git diff*)", "Bash(git status*)", "Bash(rtk git diff*)", "Bash(rtk git status*)"
]
}
}
Gotchas
These are specific to the versions above. The lessons behind them are in What broke.
rtk pytestreported “No tests collected” on a suite that passes. Run acceptance checks withrtk proxyor without the hook.- A new folder starts
blocked. The first worker in a fresh repo stopped at Claude Code’s “do you trust this folder?” prompt, soherdr agent startreturnedagent_not_ready. Worktrees inside a trusted repo didn’t ask again. - Allowlists match the rewritten command. The approval prompt shows
rtk find ..., notfind ..., so that’s the form an allowlist has to match. .claude/settings.local.jsonisn’t tracked. A new worktree doesn’t inherit the main checkout’s answers. Copy the narrow allowlist above in when you create it, not the main checkout’s accumulated one.--waitisn’t proof the turn is over. Once,agent prompt --waitcame backdonewhile the worker’s spinner was still running. A secondagent waitreturned the real reply. Don’t stop at the state change; wait until the reply line (DONEorBLOCKED) is actually inagent read.- The CodeGraph prompt hook attaches code to every prompt, including prompts about writing prose, where it’s ~15 KB of noise.
Setup checklist
The minimum to copy. I estimate under an hour, but I haven’t timed a fresh setup.
Install the tools:
# See each project's README for other platforms. # Read the install script before piping it to sh, or use the release binary / your package manager. curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh npm i -g @colbymchenry/codegraph @ast-grep/cli sudo dnf install ripgrep jq # or apt / brewRun
rtk init -g. It installs thePreToolUsehook and anRTK.mdinstructions file.Add the rest to
~/.claude/settings.json:{ "outputStyle": "Concise", "autoCompactEnabled": false, "statusLine": { "type": "command", "command": "bash ~/.claude/statusline.sh" }, "hooks": { "UserPromptSubmit": [ { "hooks": [{ "type": "command", "command": "codegraph prompt-hook" }] } ] } }Run
codegraph initin each repo you want indexed. The hook does nothing without an index.Save the statusline script above as
~/.claude/statusline.sh.Install the skills:
/plugin install mattpocock-skills@claude-plugins-official, then runsetup-matt-pocock-skillsin each repo.Write a starter
AGENTS.md(and aCLAUDE.mdthat contains@AGENTS.md):# AGENTS.md ## Rules - Verify before you claim: run it, quote the decisive line. - Never suppress a diagnostic to make it quiet. - Stay inside the scope you were given. ## Where things live - Issues: GitHub (`gh`). Decisions: `docs/adr/`. Glossary: `CONTEXT.md`. - Traps: `docs/agents/gotchas.md`. ## Communication - After changes: a few bullets. What changed and why.Optional, for the orchestrator: install herdr, run your agents inside it, and read
herdr --skill. That’s the file that teaches an agent the CLI. If you run Claude Code in auto mode, allow the herdr commands yourself in~/.claude/settings.json:{ "autoMode": { "allow": ["$defaults", "Bash(herdr*)"] } }Start a
gotchas.md. Add a line the first time something costs you more than a few minutes.At 30% on the statusline:
/handoff,/clear, “work from this handoff”.
When these versions go stale, the habits in How I Work with AI Agents still hold. If something here stopped working for you, let me know.