basecamp

A production-ready setup for Claude Code and Codex. Shared coding rules, per-project memory, an agent-neutral review gate, and token optimization.

Quick Start

git clone https://github.com/janmaaarc/basecamp.git
cd basecamp
bash setup.sh ~/Documents/your-vault

Add --with-gate to also install the review gate.

Then open ~/.claude/CLAUDE.md, fill in your stack, and follow Setup for tools and plugins. Codex users get ~/.codex/AGENTS.md generated from the same file.

What This Is

After building multiple AI and software projects with Claude Code, I found myself repeating the same setup every time. This is that setup, packaged into a reusable foundation: engineering standards, project memory, coding rules, token optimization, and safety mechanisms. Built and refined through real projects, not a template made for show.

Most coding-agent setups are minimal. This one is not. It covers:

• Global instructions your agent follows on every project, as CLAUDE.md and AGENTS.md
• Karpathy coding principles (think before coding, surgical changes)
• Commit, branch, and PR conventions
• Per-project memory via Obsidian (PROJECT, MISTAKES, CONTRACT, REQUIREMENTS files)
• Requirements checklist filtered by project type (landing/app/saas/api/automation)
• Token optimization via RTK and Headroom
• Safety hooks (block dangerous commands, scan secrets)
• Persistent memory across sessions via claude-mem
• Security scanning of .claude/ and ~/.codex/ config via agentshield
• A review gate in git, so it applies whichever agent you are using

Screenshots

Obsidian graph view (PROJECT, MISTAKES, CONTRACT linked)

RTK token savings

Video Walkthrough

Coming soon. Full setup walkthrough covering: clone, setup.sh, filling in CLAUDE.md, Obsidian graph view, and token savings demo.

Requirements

• macOS (Linux partially supported, Windows not tested)
• Claude Code or Codex, or both
• Obsidian (free, for per-project memory files)
• Homebrew (for RTK)
• Python 3.10+ (for Headroom)
• Node.js 18+ (for claude-mem)

Setup

1. Run setup script

bash setup.sh ~/Documents/your-vault

This copies all files to ~/.claude/ and your Obsidian vault. Or do it manually:

mkdir -p ~/.claude/rules
cp CLAUDE.md ~/.claude/CLAUDE.md
cp RTK.md ~/.claude/RTK.md
cp -r rules/ ~/.claude/rules/
cp -r Templates/ ~/Documents/your-vault/Templates/

2. Update CLAUDE.md

• Open ~/.claude/CLAUDE.md and fill in your stack, vault path, and defaults
• See CLAUDE.example.md for a filled-in reference
• Optional: import stack-specific rules with @rules/typescript.md, @rules/security.md, @rules/web.md, @rules/ai-agents.md, @rules/data.md, or @rules/mobile.md

3. Install tools

RTK (token savings 60-90%):

brew tap rtk-ai/tap && brew install rtk

Headroom (context compression):

Follow the official install guide: https://github.com/headroomlabs-ai/headroom

claude-mem (persistent memory):

npx claude-mem install
echo '(npx claude-mem start &>/dev/null &)' >> ~/.zshrc

agentshield (security scanner, no install needed):

npx ecc-agentshield scan

4. Install Claude Code plugins

claude plugin is a command provided by ECC. Install ECC first using the two commands below, then restart Claude Code before installing the rest.

Core (recommended for everyone):

# ECC — agents, skills, hooks (install this first)
claude plugin marketplace add affaan-m/ECC
claude plugin install ecc@ecc

# Caveman — terse responses
claude plugin marketplace add JuliusBrussee/caveman
claude plugin install caveman@caveman

# Ponytail — YAGNI coding rules
claude plugin marketplace add DietrichGebert/ponytail
claude plugin install ponytail@ponytail

# Safety hooks — block dangerous commands, scan secrets
claude plugin marketplace add poshan0126/dotclaude
claude plugin install safety-hooks@dotclaude

Optional (install what fits your stack):

# n8n workflow skills
claude plugin marketplace add czlonkowski/n8n-skills
claude plugin install n8n-mcp-skills@n8n-mcp-skills

# PostgreSQL skills
claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide

# UI design rules and auditing
claude plugin marketplace add pbakaus/impeccable
claude plugin install impeccable@impeccable

5. Install for Codex (if you use Codex)

Most of these ship a Codex build. See Switching Between Claude Code and Codex for the full list and the one exception.

# ECC's guided setup configures Claude Code and Codex in one flow
npx ecc-universal install --guided

codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail

npx skills add JuliusBrussee/caveman -a codex
npx impeccable
npx claude-mem install --ide codex-cli

# PostgreSQL skills reach Codex as an MCP server
codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide

n8n-mcp-skills installs through Codex's own plugin command; its hooks run in the plugin install, not in individual skill uploads.

Then open /hooks in Codex and approve the installed hooks.

Headroom works in Codex as an MCP server. Add to ~/.codex/config.toml:

[mcp_servers.headroom]
command = "headroom"
args = ["mcp", "serve"]

How It Works

Per-Project Memory

Every project gets a folder in your Obsidian vault:

your-vault/
  Projects/
    my-app/
      PROJECT.md      <- what the project is, current status
      MISTAKES.md     <- recurring mistakes to avoid
      CONTRACT.md     <- plan for high-risk changes
      REQUIREMENTS.md <- checklist of what shipping this project needs
  Templates/
    PROJECT.md
    MISTAKES.md
    CONTRACT.md
    REQUIREMENTS.md

Claude reads these at session start automatically. Update PROJECT.md at end of each session (max 30 lines, current status only).

Requirements Checklist

Templates/REQUIREMENTS.md is a master checklist (auth, security, SEO, AI/LLM, DevOps, etc.), each row tagged by project type: landing, app, saas, api, or automation (n8n/no-code workflow delivery). Set Type in a project's PROJECT.md and Claude generates that project's own filtered REQUIREMENTS.md, so a landing page doesn't see auth/billing rows and an n8n automation doesn't see frontend rows. Checked off only once you confirm an item is actually done, not on Claude's own say-so.

High-Risk Changes

For schema migrations, auth changes, major refactors:

1. Claude researches first. No implementation yet.
2. Claude creates CONTRACT.md with plan, risks, rollback.
3. Claude asks clarifying questions.
4. You approve.
5. Claude implements.
6. You verify.

Token Optimization

• RTK: Filters noisy bash/git/grep output before it hits Claude. 60-90% token savings on commands.
• Headroom: Compresses tool outputs (file reads, search results) before they reach Claude.
• claude-mem: Injects only relevant past context per session. No full history bloat.
• Caveman and Ponytail: Keeps responses and code minimal.

Switching Between Claude Code and Codex

Both agents read the same rules and hit the same review gate, so switching mid-project changes the model, not the setup.

Shared. setup.sh writes ~/.claude/CLAUDE.md for Claude Code and generates ~/.codex/AGENTS.md for Codex. Codex cannot resolve the @rules/*.md imports that Claude Code expands, so basecamp-sync-agents flattens them into one file. Re-run it after editing CLAUDE.md:

basecamp-sync-agents                  # ~/.claude/CLAUDE.md -> ~/.codex/AGENTS.md

Keeping AGENTS.md as a hand-written copy is what this replaces. It drifts the first time you edit the rules and nothing tells you.

This repo checks in a generated AGENTS.md so Codex reads the rules straight from a clone. CI fails any PR where it no longer matches CLAUDE.md, so edit CLAUDE.md and regenerate:

bash bin/basecamp-sync-agents ./CLAUDE.md ./AGENTS.md

The review gate is git-level, not agent-level. A pre-commit hook blocks any commit whose staged diff has not been reviewed. It fires in Claude Code, Codex, an IDE, or a plain terminal, because they all shell out to the same git.

It is opt-in, because it installs via core.hooksPath, which is global and overrides every repository's .git/hooks. Turning it on unasked would silently disable husky, lefthook or pre-commit wherever you use them.

bash setup.sh ~/Documents/your-vault --with-gate   # enable it
basecamp-reviewed                                  # record that you reviewed the staged diff
SKIP_REVIEW_GATE=1 git commit ...                  # bypass once

The marker stores a hash of the reviewed diff, not a timestamp, so changing anything staged re-arms the gate exactly.

Docs-only diffs under 15 lines skip the gate, matching the Git Rules in CLAUDE.md.

Most plugins ship a Codex build. Install them per agent:

# ECC, native Codex plugin, guided setup covers both agents at once
npx ecc-universal install --guided

# Ponytail
codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail

# Caveman
npx skills add JuliusBrussee/caveman -a codex

# PostgreSQL skills, as an MCP server
codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide

# Impeccable detects ~/.codex itself
npx impeccable

# Persistent session memory
npx claude-mem install --ide codex-cli

# RTK, instructions into AGENTS.md and RTK.md rather than hooks
rtk init -g --codex

After installing or updating anything with Codex hooks, open /hooks in Codex and approve them. Codex tracks trust per hook definition, so an update that changes a hook needs re-approval.

Headroom is provider-level. Codex reads it as an MCP server in ~/.codex/config.toml, Claude Code via ANTHROPIC_BASE_URL.

RTK installs for Codex differently. rtk init -g --codex writes instructions into AGENTS.md and RTK.md rather than patching hooks, so rewriting depends on the agent following them instead of being intercepted before the command runs.

Not available on Codex. safety-hooks ships no Codex build. Everything else here installs for both. ECC on Codex exposes instructions, skills and a reviewed hook subset, not the full Claude Code agent set, so a Codex session can record that a review happened without running the same reviewer agent.

Tools Used

Tool	Purpose	Codex	Repo	License
Headroom	Context compression proxy	Yes, as an MCP server	headroomlabs-ai/headroom	Apache 2.0
Caveman	Terse response mode	Yes	JuliusBrussee/caveman	MIT
ECC	Agents, skills, hooks	Yes, native plugin, reviewed hook subset	affaan-m/ECC	MIT
Ponytail	YAGNI coding rules	Yes	DietrichGebert/ponytail	MIT
impeccable	UI design rules and auditing (optional)	Yes, detects ~/.codex	pbakaus/impeccable	MIT
pg-aiguide	PostgreSQL skills (optional)	Yes, as an MCP server	timescale/pg-aiguide	Apache 2.0
n8n-mcp-skills	n8n workflow skills (optional)	Yes, hooks in the plugin install	czlonkowski/n8n-skills	MIT
RTK	Token-optimized CLI proxy	Yes, instruction-driven not hook-driven	rtk-ai/rtk	Apache 2.0
safety-hooks	Block dangerous commands, scan secrets	No	poshan0126/dotclaude	MIT
claude-mem	Persistent session memory	Yes, --ide codex-cli	thedotmack/claude-mem	Apache 2.0
agentshield	Scans .claude/ config for risky permissions, hooks, MCP setups	affaan-m/agentshield	MIT
code-review-graph	Codebase graph (MCP + CLI) for blast-radius analysis and token reduction on large-repo reviews (optional)	tirth8205/code-review-graph	MIT

Maintenance

# Update a plugin. `marketplace update` only refreshes the cache: installed_plugins.json
# keeps pointing at the old version, and `install` no-ops with "already installed".
# Uninstalling first is what actually switches the active version.
for p in ecc caveman ponytail; do
  claude plugin marketplace update "$p"
  claude plugin uninstall "$p@$p" && claude plugin install "$p@$p"
done

# Regenerate AGENTS.md after editing ~/.claude/CLAUDE.md, so Codex sees the same rules
basecamp-sync-agents

# Update tools
brew upgrade rtk
headroom update

Check what is actually active rather than trusting the install output:

claude plugin list

FAQ

Do I need Obsidian?

No. The per-project memory system works with any folder. Obsidian just adds graph view and backlinks. Point the vault path in CLAUDE.md to any directory.

Does this work on Windows?

Claude Code itself has limited Windows support. setup.sh requires bash. Linux is mostly supported. macOS is the primary platform.

What if I don't use RTK?

Skip it. Remove the @RTK.md import from CLAUDE.md. The rest of the setup works without it.

Do I need all the plugins?

No. Install what fits your workflow. ECC is the most useful. Caveman and Ponytail change how Claude responds. Safety hooks is optional but recommended.

Can I use this with my stack?

Yes. Fill in Your Defaults in CLAUDE.md and import the relevant rules file: @rules/typescript.md, @rules/web.md, @rules/ai-agents.md, @rules/data.md, @rules/security.md, or @rules/mobile.md.

License

MIT