agent-config

Portable brain for Claude, Codex, Cursor, OpenCode, and Pi.

This is the stuff I install on a new machine so the agent stops:

• writing like a LinkedIn ghost
• inventing a helper "for later"
• saying "Hope this helps"
• using an em dash like it pays rent

It is allowed to write less code than it wanted to. That is the whole product.

git clone git@github.com:abyigiter/agent-config.git ~/agent-config
~/agent-config/install.sh

Symlinks. Not a framework. If you want a platform, you are already lost.

What lives here

Path	Job
AGENTS.md	House rules. One file. No vibes doc.
SOUL.md	Always-on voice (ADHD). Linked into Claude and Codex.
skills/	How to code, review, debug, and draft Slack
cursor/rules/	Cursor rules. ADHD is always on. Wiki schema is globbed to wiki/** and raw/**.
opencode/opencode.json	OpenCode via OpenRouter. GLM 5.3 default, Fable planner, DeepSeek implementer. All OpenRouter models in the picker. ClickHouse, Bruin, Lightdash, Allium, Figma (desktop), Google Drive MCPs. Slack off.
pi/settings.json	Pi via OpenRouter. GLM 5.3 Flash Nitro at max thinking by default (plain GLM 5.3 / 5.3 Flash still in the cycle), plus GPT-6.1 Sol / 6 Luna / 6 Astra, Grok 4.7, Claude Sonnet 5.5 / Opus 5.5 / Haiku 5.5, DeepSeek V4 Pro, Kimi K3, Qwen 3.8, Muse Spark 1.3, and Gemini 4 Argon in the model cycle. MCPs stay in a machine-local ~/.pi/agent/mcp.json, not in the repo.
pi/models.json	Custom OpenRouter model defs Pi doesn't ship yet (Claude Haiku 5.5).
.claude/agents/, .claude/commands/	Claude Code subagents scout (Haiku 5.5), planner (Fable 5.2 default, /implement picks Fable or Opus per task) + reviewer (Opus 5.5, high effort), worker + pr-fixer (Sonnet 5.5; /implement runs worker on Haiku at max effort), and the same three chain commands. See Claude subagents.
pi/agents/, pi/prompts/	Subagents via the pi-subagents package. Builtin scout / reviewer / worker get model overrides in pi/settings.json (subagents.agentOverrides); custom planner (Gemini 4 Argon, high) and pr-fixer (Claude Sonnet 5.5, high) live in pi/agents/. Non-Claude on purpose, except pr-fixer, so PR fixes behave the same in pi and Claude Code. Chains: /implement, /scout-and-plan, /implement-and-review, /fix-pr, /debug, /test-gap, /rollout-check.
pi/extensions/*.ts	Small local Pi extensions, linked into ~/.pi/agent/extensions/. fleet-hotkey.ts: ctrl+shift+a opens /subagents-fleet.
pi/themes/	Soft Catppuccin-Macchiato palette for the Pi TUI (macchiato, active by default).

CLAUDE.md says @SOUL.md. Project AGENTS.md still wins in a repo.

Personality, in skills

Always on

Skill	Use
adhd-output	First line is the next action. Lists cap at 5. No closer.

Write code

Skill	Use
less-code	Climb the ladder. YAGNI. Reuse. Then the smallest diff.
development	One story, one PR. No "follow-up". Make, not vibes.
go	err, new(value), one TestX. Project skills still win.
react	No any. Existing UI. Typecheck is not the screen working.

Think first

Skill	Use
implement-feature	Plan mode (scout subagents gather context first), then the full slice.
writing-design-proposals	An RFC a human can actually follow.
handoff	Compact this chat for the next agent. You have to ask.

Talk to humans

Skill	Use
message	Slack is chat. yeah not Yes. One markdown fence.
pr-comment-review	Post the review. No draft. No stacked counter-PR.
fix-pr-comments	Author mode. Every bot nit. No "later".

Stolen, on purpose

Skill	Use
vercel-react-best-practices	Vercel React/Next performance
web-design-guidelines	UI/a11y review
performance	Core Web Vitals
agent-browser	Browser CLI. Prefer over Playwright
thermo-nuclear-code-quality-review	Extremely strict maintainability bar for the review-pr workflow

Local overlay

Work stuff that must not hit GitHub lives in local/ (gitignored).

local/AGENTS.append.md      glued onto ~/AGENTS.md
local/skills/<name>/        extra skills, same symlink treatment

No local/ folder? Clone stays generic. That is the point.

What the installer links

~/AGENTS.md
~/CLAUDE.md
~/.claude/CLAUDE.md
~/.claude/AGENTS.md
~/.claude/SOUL.md
~/.codex/AGENTS.md
~/.codex/SOUL.md
~/.agents/skills/<skill>
~/.claude/skills/<skill>
~/.claude/agents/*.md
~/.claude/commands/*.md
~/.codex/skills/<skill>
~/.cursor/rules/*.mdc
~/wiki/AGENTS.md              (if ~/wiki exists; wiki schema, not always-on)
~/.config/opencode/opencode.json
~/.config/opencode/AGENTS.md
~/.pi/agent/settings.json
~/.pi/agent/models.json
~/.pi/agent/agents/*.md
~/.pi/agent/prompts/*.md
~/.pi/agent/extensions/*.ts

OpenCode picks up skills from ~/.agents/skills natively, so no extra links. Bruin, Lightdash, and Allium MCPs read tokens from ~/.config/opencode/{bruin,lightdash,allium}.token (not in the repo). ClickHouse and Google Drive use OAuth: opencode mcp auth <name>. Figma uses the Figma desktop app's local MCP server (remote Figma MCP only allowlists other clients). Slack is disabled: its MCP needs a pre-registered Slack app.

Pi reads skills from ~/.agents/skills natively too. Its MCPs mirror the OpenCode set from the machine-local ~/.pi/agent/mcp.json (not in the repo) and read the same token files. OAuth servers sign in with pi mcp login <name>.

Subagent workflows

The parent session drives every chain: it runs one subagent per stage, waits for it to finish, and passes its output into the next stage's task. scout, planner, and reviewer are read-only recon and review; worker and pr-fixer are the only roles that edit files and run the checks.

/implement

flowchart LR
    R([request]) --> S["scout"]
    S -- "context + original task" --> P["planner"]
    P -- "plan + original task" --> W["worker"]
    W --> O(["worker report"])

Loading

Claude Code differs: the session picks the planner model per task (Fable for large or ambiguous work, Opus for small or scoped work), worker runs on Haiku at max effort through the Agent tool (no Pi), and a final fast review runs: reviewer (Opus 5.5, medium) reads the diff and reports. It does not apply fixes.

Sources: Claude Code · Pi

/scout-and-plan

flowchart LR
    R([request]) --> S["scout"]
    S -- "context + original task" --> P["planner"]
    P --> O(["returned plan"])

Loading

No edits: both stages are read-only, and no worker runs.

Sources: Claude Code · Pi

/implement-and-review

The fix stage differs by platform. Claude Code only runs the fix worker when the reviewer flags Bugs or Design issues. Pi always runs it and tells it to change nothing when the verdict is OK with no findings. The reviewer runs once either way.

flowchart TB
    subgraph CC["Claude Code"]
        direction LR
        A([request]) --> B["worker"]
        B -- "original task + worker report" --> C["reviewer"]
        C -. "inspects" .-> D[("current diff")]
        C --> E{"Bugs or Design issues?"}
        E -- "yes" --> F["fix worker<br/>review + original task"]
        E -- "no" --> G(["final worker report<br/>+ reviewer verdict"])
        F --> G
    end
    subgraph PP["Pi"]
        direction LR
        H([request]) --> I["worker"]
        I -- "original task + worker report" --> J["reviewer"]
        J -. "inspects" .-> K[("current diff")]
        J --> L["fix worker<br/>no changes when verdict is OK with no findings"]
        L --> M(["final worker report<br/>+ reviewer verdict"])
    end

Loading

Sources: Claude Code · Pi

/fix-pr

You describe a fix for your own PR; pr-fixer (Sonnet 5.5) makes it on the checked-out PR head. The main session then makes a new follow-up commit (never an amend). It pushes only if you pass push. Review comments are not read: that is /fix-pr-reviews.

flowchart LR
    U(["PR + your fix request"]) --> F["pr-fixer<br/>edit + scoped checks"]
    F --> C(["main session: follow-up commit, push only on push"])

Loading

Sources: Claude Code · Pi

/debug, /test-gap, /rollout-check

Both platforms. The Pi versions use the same stages with the Pi model overrides.

flowchart LR
    subgraph D["/debug"]
        direction LR
        D1(["symptom"]) --> D2["scout<br/>trace code path"]
        D2 --> D3["planner<br/>ranked hypotheses + checks"]
        D3 --> D4["worker<br/>run checks, fix confirmed cause"]
    end
    subgraph T["/test-gap"]
        direction LR
        T1(["current diff"]) --> T2["reviewer<br/>untested behavior"]
        T2 --> T3["worker<br/>tests only"]
    end
    subgraph R["/rollout-check"]
        direction LR
        R1(["manifest diff"]) --> R2["scout<br/>manifests per env"]
        R2 --> R3["reviewer<br/>drift + rollout risk"]
    end

Loading

/debug edits nothing if no hypothesis is confirmed. /test-gap never edits production code. /rollout-check is read-only end to end.

Sources: debug (Claude Code · Pi) · test-gap (Claude Code · Pi) · rollout-check (Claude Code · Pi)

Pi subagents

After ./install.sh, run /reload in pi (or start a new session).

Chain diagrams: Subagent workflows.

Agent	Model	Defined in
scout	GPT-6 Luna (low thinking)	pi-subagents builtin, model override in pi/settings.json
planner	Gemini 4 Argon (high)	pi/agents/planner.md (read-only tools)
reviewer	GPT-6.1 Sol	builtin + override
worker	GLM 5.3 Flash Nitro :nitro:max	builtin + override
pr-fixer	Claude Sonnet 5.5 (high)	pi/agents/pr-fixer.md (edit tools, used by /fix-pr)

Other builtins (researcher, oracle, delegate, evidence-auditor, ...) inherit the session model.

Chains:

/implement add input validation to the signup handler      # scout -> planner -> worker
/scout-and-plan migrate auth to OAuth                       # scout -> planner, no edits
/implement-and-review add retry to the webhook client      # worker -> reviewer -> worker
/review-pr 42                                              # scout -> reviewer; your PR: markdown only, peer PR: posts review
/fix-pr-reviews 42 commit                                  # scout -> planner -> worker; replies on disagree threads, commit/push only if asked
/fix-pr 42 handle nil wallet in transfer push              # pr-fixer edits, main session commits; push only if asked

Single agent or parallel, in plain English:

use scout to find where session tokens are validated
use reviewer to review my uncommitted changes
run 3 scouts in parallel: one for the API routes, one for the DB layer, one for the tests

Watching runs:

• FleetView sits under the editor and lists active runs. /subagents-fleet (or ctrl+shift+a, from pi/extensions/fleet-hotkey.ts) opens the live inspector: browse children, read transcripts, steer, or stop.
• Chains usually run async. Ask "show active async runs" to check on them.
• /subagents-doctor checks the setup. /subagents-guide [topic] has the built-in docs.

Notes:

• Each subagent is a separate pi process with a fresh context. Write tasks for someone who hasn't read the conversation.
• pi-subagents loads a repo's .pi/agents/ by default (agentScope: "both"), and project agents win name collisions. Only run it in repos you trust.
• To change a builtin's model, edit subagents.agentOverrides in pi/settings.json. Don't copy a builtin into pi/agents/, because a same-name file replaces the bundled definition wholesale. Exception: the /review-pr workflow pins its reviewer to openrouter/openai/gpt-6.1-sol per-run in pi/prompts/review-pr.md, so PR review stays on GPT-6.1 Sol even if the override changes.
• The chain prompts embed a js workflow script (the pi-subagents workflow API). The legacy chain parameter is no longer supported.

Claude subagents

The same five roles and chains as Pi, for Claude Code. Chain diagrams: Subagent workflows.

Agent	Model	Tools
scout	Haiku 5.5	Read, Grep, Glob, Bash (read-only)
planner	Fable 5.2, effort: medium (/implement overrides with Fable or Opus per task)	Read, Grep, Glob
reviewer	Opus 5.5, effort: high	Read, Grep, Glob, Bash (read-only)
worker	Sonnet 5.5 (/implement overrides with Haiku, effort: max)	all
pr-fixer	Sonnet 5.5	Read, Edit, Write, Grep, Glob, Bash

/scout-and-plan migrate auth to OAuth                     # scout -> planner, no edits
/implement add input validation to the signup handler    # scout -> planner -> worker
/implement-and-review add retry to the webhook client    # worker -> reviewer -> worker (fix pass only if needed)
/review-pr 42                                            # scout -> reviewer; your PR: markdown only, peer PR: posts review
/fix-pr-reviews 42 commit                                # scout -> planner -> worker; replies on disagree threads, commit/push only if asked
/fix-pr 42 handle nil wallet in transfer push            # pr-fixer edits, main session commits; push only if asked
/debug 502 on POST /transfers after deploy             # scout -> planner (ranked hypotheses) -> worker (check, then fix)
/test-gap                                                # reviewer finds untested changes -> worker writes tests only
/rollout-check apps/omsx                                 # scout -> reviewer, read-only dev/stg drift and rollout risk

• The polygon-core plugin's guard-agent-model-pin hook blocks Agent calls that don't pass model. That parameter only takes aliases and overrides the frontmatter, so the commands pass haiku / opus / sonnet explicitly. The frontmatter full IDs still apply when you call an agent directly without the hook.
• haiku resolves to Haiku 4.5 by default. To get 5.5, set "env": { "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5" } in the machine-local ~/.claude/settings.json (not in the repo).

Not in this repo

Secrets, tokens, session history, SQLite, caches, and the local/ overlay.

If it can get you fired or phished, it does not belong here.