.config/agents

This is my Agent Harness configuration. Tell your agent to clone it to ~/.config/agents and symlink the parts you want into your harness.

Public guide: vedang.me/dotagents.

Example setup (pi-coding-agent)

git clone https://github.com/vedang/dotagents ~/.config/agents
mkdir -p ~/.pi/agent
ln -s ~/.config/agents/AGENTS.md ~/.pi/agent/AGENTS.md
ln -s ~/.config/agents/APPEND_SYSTEM.md ~/.pi/agent/APPEND_SYSTEM.md
ln -s ~/.config/agents/pi-settings.json ~/.pi/agent/settings.json
ln -s ~/.config/agents/agents ~/.pi/agent/agents
ln -s ~/.config/agents/prompts ~/.pi/agent/prompts
ln -s ~/.config/agents/pi-extensions ~/.pi/agent/extensions
ln -s ~/.config/agents/skills ~/.pi/agent/skills

Claude Code setup

The claude/ directory holds the Claude Code surface of this harness: CLAUDE.md (symlink to the shared AGENTS.md), settings.json (Explanatory output style, notification hooks, statusline, permissions), ported subagent role cards under claude/agents/, and skills under claude/skills/ (claude-specific skills plus symlinks to the shared skills/).

See docs/install-claude.md for the symlink setup into ~/.claude, the pi→Claude surface map, and what replaces each pi package. Migration plans for my own pi extensions live in docs/claude-compat-*.md.

Weekly local session analysis

Runbook: scripts/README.md. On Sunday, run from repository root:

python3 scripts/session_analysis.py --week-ending YYYY-MM-DD

Replace YYYY-MM-DD with Sunday date. Generated session_analysis/ data stays local and ignored.

Current Pi runtime profile

Source of truth: pi-settings.json.

Core defaults

Setting	Value	Notes
`defaultProvider`	`openai`	Sign in with ChatGPT through `/login openai`.
`defaultModel`	`gpt-6.1-sol`	Default model for new sessions.
`defaultThinkingLevel`	`medium`	Moderate reasoning by default.
`defaultTools`	`["+codemode"]`	Add codemode alongside the standard tools.
`steeringMode`	`all`	Apply steering globally.
`followUpMode`	`one-at-a-time`	Sequential follow-up flow.
`hideThinkingBlock`	`false`	Show thinking block.
`theme`	`system`	Follow the terminal palette using Pi's native theme support.
`compaction.enabled`	`true`	Context compaction on.
`compaction.reserveTokens`	`16384`	Reserved token budget.
`compaction.keepRecentTokens`	`12000`	Keep recent context before compacting.

Enabled models

deepseek/deepseek-flash
local/mlx-community/Qwen3.8-27B-4bit
openai/gpt-5.6-terra
moonshotai/kimi-k3
zai/glm-5.3
openai/gpt-6-astra
openai/gpt-6-luna
openai/gpt-6-sol
openai/gpt-6.1-sol
anthropic/claude-opus-5-5
anthropic/claude-sonnet-5-5
anthropic/claude-fable-5-1

Agent model assignments

Built-in scout, worker, and reviewer assignments live in subagents.agentOverrides in pi-settings.json; custom roles live in agents/.

Role	Model	Thinking
Scout	`openai/gpt-6-luna`	`low`
Worker	`openai/gpt-6.1-sol`	`medium`
Reviewer	`openai/gpt-6.1-sol`	`high`
Planner	`openai/gpt-6.1-sol`	`high`
Plan-reviewer	`openai/gpt-6-astra`	`high`
Multimodal	`openai/gpt-6-luna`	`medium`
Researcher	`openai/gpt-6-luna`	`medium`

Each role has one primary model; obsolete fallbackModels declarations are removed. Restart Pi after updating. Resumed sessions retain their previous model selection; select the new OpenAI model explicitly when continuing an older session.

The pi-better-openai package and its local configuration are removed. Its image-generation and usage-display features are no longer loaded; native ChatGPT login supplies authentication, not replacement extension tools.

Packages loaded from `pi-settings.json`

Package	Source	Purpose
`pi-askuserquestion`	`git:github.com/ghoseb/pi-askuserquestion`	Structured multi-choice questions via `ask_user_question`.
`pi-interactive-shell`	`npm:pi-interactive-shell`	Overlay, dispatch, and monitor workflows for interactive CLI agents.
`dafny-estimation`	`git:github.com/unravel-team/dafny-estimation`	Formal specification-driven project estimation skill.
`caveman`	`git:github.com/vedang/caveman`	Token-efficient caveman response mode plus terse helper skills.
`pi-boomerang`	`git:github.com/vedang/pi-boomerang`	Collapse large task context into compact summaries.
`pi-custom-provider-zai`	`git:github.com/vedang/pi-custom-provider-zai`	Registers ZAI-hosted GLM models as custom provider models.
`pi-prompt-history`	`git:github.com/vedang/pi-prompt-history`	Prompt-history search for past session inputs.
`pi-quizme`	`git:github.com/vedang/pi-quizme`	Quiz-style recall and change-comprehension checks.
`pi-ralph-loop`	`git:github.com/vedang/pi-ralph-loop`	Ralph-style autonomous planning loops via `/ralph` commands.
`pi-simplify-code`	`git:github.com/vedang/pi-simplify-code`	Refactor/simplify changed code without changing behavior.
`pi-subagents`	`git:github.com/vedang/pi-subagents`	Subagent execution, parallel work, and chain orchestration.
`visual-explainer`	`git:github.com/vedang/visual-explainer`	Generate self-contained HTML visual explainers.
`pi-read-map`	`git:github.com/Whamp/pi-read-map`	Better large-file reads with structure maps.
`chrome-cdp-skill`	`git:github.com/pasky/chrome-cdp-skill`	Interact with live local Chrome tabs through CDP.
`pi-autoresearch`	`git:github.com/davebcn87/pi-autoresearch`	Autonomous experiment loop with metrics tracking and confidence scoring.

Repository contents

Root configuration files

File	Description
`AGENTS.md`	Global workflow rules: `jj`, planning folders, tests, commits, tagref.
`APPEND_SYSTEM.md`	Extra system-prompt guidance layered into the harness.
`pi-settings.json`	Pi runtime defaults, enabled models, and package list.

`agents/` role cards

File	Description
`context-builder.md`	Builds codebase context and a planner-ready meta-prompt from requirements.
`multimodal.md`	Reads PDFs, images, and other media for implementation details.
`plan-reviewer.md`	Critiques plans for missing steps, bad assumptions, and risk.
`planner.md`	Turns scoped context into a concrete implementation plan.
`researcher.md`	Runs focused web research and produces a source-backed brief.
`reviewer.md`	Reviews implementation quality and can make small follow-up fixes.
`scout.md`	Fast codebase recon with compressed handoff context.
`worker.md`	General-purpose implementation subagent for scoped coding work.

`agents/` chain workflows

File	Description
`full-workflow.chain.md`	Scout → plan → review plan → implement → review. Main agent still owns tests and commits.
`implement-plan.chain.md`	Implement a pre-created plan, then run a review pass. Main agent still owns tests and commits.
`quick-plan.chain.md`	Fast scout → plan workflow without a plan review pass.
`scout-and-plan.chain.md`	Scout code, create a plan, then review the plan.

`prompts/`

Reusable prompt templates and operator instructions.

File	Description
`orchestration-watchdog.md`	Starts a verified periodic headless Pi watchdog that wakes the master for cross-workspace orchestration checks.
`sharpen-communication.md`	Rewrites communication with BLUF/MECE structure and stronger phrasing.

`pi-extensions/`

Checked-in local runtime extensions.

File	Description
`explanatory-output-style.ts`	Appends explanatory-output guidance to the system prompt.
`handoff.ts`	Adds `/handoff` to draft a focused prompt for a new session.
`notify.ts`	Sends terminal-native notifications when Pi is ready again.
`status-line.ts`	Demonstrates persistent footer status updates across session turns.

`skills/`

Checked-in local skills in this repo.

Skill	Description
`docx/`	Create, edit, and analyze Word `.docx` documents.
`pdf/`	Extract, edit, merge, split, OCR, and otherwise process PDFs.
`pptx/`	Read, edit, and create PowerPoint `.pptx` decks.
`skill-creator/`	Create or update reusable agent skills.
`xlsx/`	Create, edit, and validate spreadsheet outputs.

Skills provided by installed packages

These are available at runtime through packages in pi-settings.json, even though they are not stored under this repo's skills/ directory.

Skill	Provided by	Description
`caveman`	`caveman`	Ultra-compressed communication mode for token efficiency.
`caveman-commit`	`caveman`	Terse Conventional Commits helper.
`caveman-help`	`caveman`	Quick reference for caveman commands and modes.
`caveman-review`	`caveman`	One-line compressed code review comments.
`caveman-compress`	`caveman`	Compress natural-language memory files while preserving technical content.
`dafny-estimation`	`dafny-estimation`	Risk-adjusted project estimation using Dafny specs.
`visual-explainer`	`visual-explainer`	HTML visual explainers for plans, systems, and diffs.
`chrome-cdp`	`chrome-cdp-skill`	Inspect and interact with live local Chrome tabs.
`interactive-shell`	`pi-interactive-shell`	Cheat sheet and workflow for launching TUI coding agents.
`codex-cli`	`pi-interactive-shell`	Codex CLI reference material.
`gpt-5-4-prompting`	`pi-interactive-shell`	Prompting guidance for GPT-5.4.
`codex-5-3-prompting`	`pi-interactive-shell`	Prompting guidance for Codex 5.3.

Name		Name	Last commit message	Last commit date
.beads		.beads
.github/workflows		.github/workflows
.pi		.pi
agents		agents
chains		chains
claude		claude
docs		docs
dotagents		dotagents
extension_config		extension_config
images		images
pi-extensions		pi-extensions
prompts		prompts
scripts		scripts
skills		skills
specific_skills		specific_skills
.gitignore		.gitignore
.jscpd.json		.jscpd.json
AGENTS.md		AGENTS.md
LICENSE.txt		LICENSE.txt
Makefile		Makefile
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
context.md		context.md
hermes-config.yaml		hermes-config.yaml
knip.json		knip.json
package.json		package.json
pi-models.json		pi-models.json
pi-settings.json		pi-settings.json
tsconfig.json		tsconfig.json
vitest.config.integration.ts		vitest.config.integration.ts
vitest.config.llm.ts		vitest.config.llm.ts
vitest.config.unit.ts		vitest.config.unit.ts

Navigation Menu

Repository navigation

About

Repository files navigation

.config/agents

Example setup (pi-coding-agent)

Claude Code setup

Weekly local session analysis

Current Pi runtime profile

Core defaults

Enabled models

Agent model assignments

Packages loaded from `pi-settings.json`

Repository contents

Root configuration files

`agents/` role cards

`agents/` chain workflows

`prompts/`

`pi-extensions/`

`skills/`

Skills provided by installed packages

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

.config/agents

Example setup (pi-coding-agent)

Claude Code setup

Weekly local session analysis

Current Pi runtime profile

Core defaults

Enabled models

Agent model assignments

Packages loaded from pi-settings.json

Repository contents

Root configuration files

agents/ role cards

agents/ chain workflows

prompts/

pi-extensions/

skills/

Skills provided by installed packages

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Packages loaded from `pi-settings.json`

`agents/` role cards

`agents/` chain workflows

`prompts/`

`pi-extensions/`

`skills/`