This is the meta post — the one that ties together everything from this series into a single, copy-pasteable setup guide. Each tool has install commands, each step says why it matters.
I wrote this because I'm lazy. Turns out that's a quality in a developer. I want to bookmark this, point an agent at it on a new system, and have it set everything up. I'll spend a day debugging things that will save me ten minutes every day from then on. Fix and forget. Automate myself out of the loop.
What this covers
This series has six articles so far. Each focused on one angle. This one combines them into a single end-to-end setup you can run in a weekend.
You don't need all of it on day one. Each phase has a clear stopping point. Do one, ship something, come back for the next.
Phase 0: Compression tools — install these first
Before any project setup, install the three tools that reduce token waste. They work together: Caveman compresses how you write specs, Ponytail compresses how agents write code, RTK compresses tool output. Each is a CLI plugin for your agent of choice — install the ones that fit your setup.
Ponytail — makes agents write less code (~54% less LOC proven)
Why: Agents over-build. A date picker becomes a flatpickr installation, a wrapper component, a stylesheet, and a timezone discussion. Ponytail stops them at the first rung of a ladder: "Does this need to exist? Does stdlib do it? Native platform feature? One line? Only then: the minimum."
What it changes: Before writing code, the agent runs a YAGNI ladder. The code ends up small because it's necessary, not golfed. Never cuts validation, error handling, security, or accessibility.
Benchmarked on real Claude Code sessions: 54% less code, 22% fewer tokens, 20% cheaper, 27% faster, 100% safe.
Install for your agent:
# Claude Code
/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail
# Pi agent
pi install git:github.com/DietrichGebert/ponytail
# Codex
codex plugin marketplace add DietrichGebert/ponytail
# Hermes
hermes plugins install DietrichGebert/ponytail --enable
# Cursor / Windsurf / Cline — copy .cursor/rules/ or .clinerules/ from the repo
# https://github.com/DietrichGebert/ponytail
Slash commands after install:
-
/ponytail lite|full|ultra|off— set intensity -
/ponytail-review— review current diff for over-engineering -
/ponytail-audit— audit the whole repo -
/ponytail-debt— harvest deferred shortcuts
Why you'd do it: Every line an agent writes costs tokens to produce and context to hold. Ponytail cuts both. One install, always-on effect.
Caveman — compressed spec writing (~75% less tokens)
Why: Long-winded prompts cost more and leave more room for the agent to misinterpret. Caveman strips filler, pronouns, pleasantries, and courtesies — fragments only. The same instruction in 25% of the tokens.
What it changes: You write specs and prompts in compressed form. The agent still understands them the same way.
Install:
# Pi agent (as extension)
pi install npm:@fgladisch/pi-caveman
# Or add to Pi settings.json:
# "packages": ["npm:@fgladisch/pi-caveman"]
# Claude Code — add to CLAUDE.md:
# Compression: omit filler, pronouns, pleasantries. Fragments only.
Why you'd do it: Every word in your prompt multiplies across every response token. Less fluff in = less fluff out. Also forces you to be precise — vague instructions can't hide behind padding.
RTK (Rust Token Killer) — reduces tool output 60-90%
Why: ls, git status, pytest output, npm audit — these commands dump noise into your LLM context. RTK intercepts them, compresses the output, and only passes the signal.
What it changes: It's a CLI proxy. 100+ supported commands. <10ms overhead per call. Single Rust binary.
Install:
# macOS
brew install rtk-ai/rtk/rtk
# Or from source
git clone https://github.com/rtk-ai/rtk
cd rtk && cargo install --path .
# Init for your agent
rtk init --agent claude # Claude Code
rtk init --agent hermes # Hermes Agent
rtk init --agent pi # Pi agent
# Or globally
rtk init
Why you'd do it: When a single ls -la in a monorepo dumps 200+ lines into context, and npm list adds another 300, RTK cuts that to the actual signal. In long sessions, this saves millions of tokens.
Phase 1: Project docs baseline
The single highest-leverage thing you can do. An agent relearns your project every session unless you give it somewhere to look.
Copy-paste: the docs scaffold
mkdir -p docs/SPECS && cat > AGENTS.md << 'EOF'
# AGENTS.md
Before writing code: read this file, then check docs/ for known issues,
the data model, and project conventions. Tests must pass after changes.
All project knowledge lives in docs/. Single source of truth.
Read docs/BUGS.md, docs/LESSONS.md, and docs/TECH-DEBT.md before any work.
EOF
touch docs/BUGS.md docs/LESSONS.md docs/TECH-DEBT.md
echo "✅ docs/ + AGENTS.md created"
What each file is for
| File | Purpose |
|---|---|
AGENTS.md |
Agent entry point — how to think about this project |
docs/BUGS.md |
Bug catalog with root causes, symptoms, fixes |
docs/LESSONS.md |
Things that went wrong — institutional memory |
docs/TECH-DEBT.md |
Anti-pattern inventory with phased fix plan |
docs/SPECS/ |
Feature specs — one plan per feature |
docs/SCHEMA.md |
Data model reference (optional but valuable) |
Claude CLI: hand this to an agent
claude -p "
Create docs/ and AGENTS.md in this project.
- mkdir -p docs/SPECS
- Write AGENTS.md that tells the agent to read docs/ before coding
- touch docs/BUGS.md, docs/LESSONS.md, docs/TECH-DEBT.md
Read the codebase first. Keep the files honest.
"
Why this matters
Without this, your agent wastes context rediscovering what the project does and what it shouldn't do. A single AGENTS.md + docs/ folder saves 200K+ tokens of exploratory waste per session. It's the single highest-leverage thing you can do.
Phase 2: Auth + testing
This is the hard part. It determines how much AI can assist and how much trust you can hand over.
Persistent browser profile
Most apps won't let an agent in without MFA or SSO. Solve it once:
# You do this — one-time manual login
npx playwright open --save-storage=.auth/profile.json
# Login manually in the headed browser window
# profile.json now saves the session — reuse everywhere
Add to CLAUDE.md
## Auth
- Persistent browser profile at .auth/profile.json
- Created via `npx playwright open --save-storage=.auth/profile.json`
- Login once, reuse forever. Covers MFA, SSO, redirect chains.
- Do NOT use CDP (Chrome DevTools Protocol) — flakes on connection drops
Agent: write the first test
claude -p "
Write one E2E test for the main auth flow.
- Use Playwright with .auth/profile.json
- Keep it simple: login, navigate to dashboard, verify a known element
- Tests live in tests/
- Run it and confirm it passes
"
Why this matters
Without auth working, the agent can't test anything it builds. With a persistent profile, every session starts ready to work — the agent spends zero context on re-authenticating.
Phase 3: MCP servers
MCP servers give your agent tools it doesn't have natively. Install these, configure them, and the agent discovers them automatically.
Playwright MCP — agent drives a real browser
Why: The agent navigates to URLs, clicks buttons, reads the DOM, takes screenshots. Drop a link and describe a bug — the agent reproduces it, inspects the mismatch, and writes a fix. Uses the same persistent profile from phase 2, so auth just works.
Install:
# Install Playwright
npm install -D @playwright/test
npx playwright install chromium
# Install MCP server
npm install -D @anthropic-ai/mcp-playwright
Configure in project MCP config:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@anthropic-ai/mcp-playwright"],
"env": {
"PLAYWRIGHT_BROWSER_TYPE": "chromium"
}
}
}
}
Claude CLI — verify it works:
claude -p "Use playwright to open https://example.com and tell me the page title"
Context7 MCP — up-to-date library docs
Why: When the agent needs to use an unfamiliar API, it queries Context7 instead of guessing or hallucinating. React, Fastify, GraphQL, Playwright — anything with published docs.
Install:
# Get your API key from https://context7.com
# Then configure in your MCP config
Configure:
{
"mcpServers": {
"context7": {
"url": "https://mcp.context7.com/mcp",
"headers": {
"CONTEXT7_API_KEY": "your-key-here"
}
}
}
}
Claude CLI — verify it works:
claude -p "Use context7 to check the latest React Server Components API"
Why these two
- Playwright MCP turns "this page has a bug" from a manual reproduction into a one-prompt fix
- Context7 MCP stops the agent from hallucinating API signatures — it queries real docs
Phase 4: Agent instructions
Now the agent needs to know how to think about your project. This goes in CLAUDE.md (Claude Code), AGENTS.md (universal), or the equivalent for your agent.
Copy-paste: ORA workflow
# Agent Instructions
## On complex tasks
Decompose → route → delegate → compress → verify.
## Routing
- lookup/research → cheap model (Flash, 3B local)
- code_gen/review → mid model (DeepSeek, 7B)
- debug/architecture → flagship (Sonnet, Pro)
## Compression (mandatory)
1. Omit filler, pronouns, pleasantries. Fragments only.
2. YAGNI ladder: exist? → stdlib? → native? → one line? → minimum.
3. RTK: group similar items, deduplicate, truncate redundancy.
4. Never cut: validation, error handling, security, accessibility.
## Exit criteria
Every subtask must have a verifiable exit criterion:
- File exists: `path/to/file.ext`
- Command passes: `npm test`
- Pattern found: `grep -q "func" file.go`
Do not trust self-reports. Verify.
Claude CLI setup
npm install -g @anthropic-ai/claude-code
# Start a session
claude
# One-shot a task
claude -p "add a user profile page with tests"
# From a spec file
claude -p "$(cat docs/SPECS/user-profile.md)"
# With specific model
claude --model sonnet -p "refactor the API handler"
Pi agent setup
# Install Pi
npm install -g @earendil-works/pi-coding-agent
# Usage
pi -p "fix the login button alignment"
pi -p --model Qwable-9B "refactor the API handler"
pi --mode rpc "implement the user profile page"
Why this matters
Without instructions, the agent defaults to its generic behaviour — which treats every task the same way. With these instructions, it decomposes complex work, routes to the cheapest model, compresses everything, and verifies results. The same agent, 10x more efficient.
Phase 5: The delivery loop
Docs, auth, MCP, and instructions exist. What connects them is the workflow.
The cadence
1. Write a spec → docs/SPECS/feature-name.md
2. Agent implements against it
3. Tests run — pass or fail
4. Agent fixes or you review the output
5. Commit
With Claude CLI
# 1. Write spec
cat > docs/SPECS/add-search.md << 'EOF'
## Spec: Add full-text search
- Endpoint: GET /api/search?q={term}
- Returns: paginated results with score
- Auth: requires API key
- Tests: 2 unit, 1 integration
EOF
# 2. Run agent against spec
claude -p "Implement the spec at docs/SPECS/add-search.md. Read AGENTS.md first. Run tests after."
# 3-5. Review output, fix if needed, commit
git add -A && git commit -m "feat: add full-text search"
Compress before sending
Before → after with the three compression tools:
# Before (bloated)
claude -p "Hey, could you implement a search feature for the API? Basically users type a query and get results back. Let me know what you think!"
# After (compressed — Caveman style)
claude -p "Implement: GET /api/search?q={term}. Paginated + score. API key auth. 2 unit + 1 integ. Spec: docs/SPECS/add-search.md"
The five things to check before delivery
- What does "done" look like from their side? — Ask before starting
- When will they actually look at it? — Name a review date alongside delivery
- What needs to be perfect vs improvable? — Two buckets agreed early
- Could they see something before full delivery? — Mid-point check-in
- Do they have the full picture? — Quick walkthrough at handover
Phase 6: Troubleshooting common failures
Lessons from an auto-fix pipeline that took three iterations to still not work:
Don't retry OOM
Two independent consumers + retry loops = cascade failure on memory error. Serialize access to your model server. Stop retrying on 507.
Use the local binary, not npx
# Instead of:
npx playwright test
# Use:
./node_modules/.bin/playwright test
NPX adds overhead and can introduce version mismatches in automated pipelines.
Measure what your model server can hold
# Check available memory
vm_stat
# Monitor model server
ps aux | grep llama
The article tree
| Article | What it covers |
|---|---|
| What Actually Changed in Two Weeks | The baseline — docs, tests, schema |
| Three Loops, No Ship | Auto-fix failures, retry spirals, local model limits |
| How to Onboard an Existing Project with AI Tools | Full 4-phase onboarding guide |
| More Watts, Less Light | Token efficiency — Caveman, Ponytail, RTK |
| Five Things to Check When Delivering Fast | Human-side delivery checklist |
| A Weekend of Testing | What models can do now |
When to stop
You don't need all six phases. The minimum viable setup is:
- AGENTS.md or CLAUDE.md — one file telling the agent how to think
- One auth'd E2E test — proves the agent can work in your app
- One MCP server — Playwright or Context7
- One compression tool — Ponytail is the highest-impact single install
That's four things. Everything else is compound returns. Pick one, move it forward, stop when you've made progress.
Top comments (0)