codehere

Your AI agents shouldn't lock you in. Codehere keeps your memory, audit, safety, and reports portable across every coding agent you use.

Codehere is the vendor-neutral layer between you and the coding agents you already use — Claude Code, Codex, Aider, Gemini, OpenCode. One npm install. Local-first, OSS, no account, no IAM, no compliance prereqs. Switch agent, keep your memory. End the day with one Final Report covering everything they did.

All 5 adapters (Claude Code, Codex, Aider, Gemini, OpenCode) ship adapter code for session-tracing, Final Reports, and trust scoring. Claude Code additionally gets full pre-execution safety-hook enforcement on every tool call via the Claude Agent SDK. The memory, audit log, failover, and Final Report surfaces are wired across all 5 adapters today.

Honest status (2026-05-19) — The 1200 internal tests verify codehere's code against codehere's own assumptions about what each adapter emits. They do not systematically verify against real-adapter outputs in production. Real-adapter contract verification is the v0.7 release work — see docs/TRUTHFUL_STATE_2026-05-19.md for the verified / assumed / unverified classification of every surface.

The enterprise tier is owned by OpenAI Frontier (8-14 weeks of deploy prereqs, sales-team gated) and Anthropic Cowork (paid Claude subscription, single-vendor). Codehere fills the gap they structurally can't reach: the individual / small-team / no-IT-department tier, vendor-neutral.

See docs/STRATEGIC_VISION.md Appendix C and docs/figures/positioning-matrix.svg for the full positioning chart.

One layer, every agent, your work stays portable.

Recipe — setup to first audit in 30 minutes

One folder convention, one prompt formula, four ready-to-use prompts. Full version: docs/RECIPE.md.

Setup (once)

| | | | |---|---|---| | 1 | Install | npm install -g codehere (Node 20+) — v0.6.0 is the current stable | | 2 | Detect environment | codehere setup — checks API key, finds your repo | | 3 | Install the safety hook | codehere hook install — every Claude Code tool call now audited | | 4 | Install at least one specialist | Claude Code: npm i -g @anthropic-ai/claude-code (Codex / Aider / OpenCode / Gemini also supported · see docs/integrations/ for Cursor MCP setup) | | 5 | Scaffold this repo | cd /your/repo && codehere init — creates .codehere/ with the F3 memory tree (working / episodic / semantic / personal / candidates) plus AGENTS.md (project briefing) and skills/ (prompt templates) | | 6 | Fill in AGENTS.md | 5 minutes. The agent will follow what's written there. | | 7 | Build the symbol map (optional) | codehere memory repo-map — JSON map of every top-level export in your repo, ranked by reference count. Spawned agents read it on entry instead of cold-grepping. |

You're done. codehere start opens the web UI at :3773; you delegate from there.

The prompt formula

Context  +  End State  +  Constraints

• Context — "Read .codehere/CONTEXT.md" + any specific files
• End State — the user-visible change, the test that passes, the file that exists
• Constraints — files not to touch, dependencies not to add, patterns not to use

Folder convention (what codehere init writes)

The v0.6 layout — F3 project memory:

| Path | Purpose | Committed? | |---|---|---| | .codehere/AGENTS.md (or legacy CONTEXT.md) | What this repo is. Conventions. Style. Constraints. | yes | | .codehere/memory/working/session.md (or legacy HANDOVER.md) | What's in flight in the current session. | no | | .codehere/memory/episodic/AGENT_LEARNINGS.jsonl | Symlink to your full session history at ~/.codehere/sessions.jsonl. | (symlink) | | .codehere/memory/episodic/repo_map.json | Ranked symbol map. Built by codehere memory repo-map. | yes | | .codehere/memory/semantic/lessons.jsonl | Project-specific lessons promoted from episodic patterns. | yes | | .codehere/memory/personal/preferences.json | Per-developer prefs. | no | | .codehere/skills/<name>/SKILL.md (or legacy flat PROMPTS.md) | Prompt templates — one folder per skill. | yes | | .codehere/protocols/permissions.md + hook_patterns.json | Safety policy for the PreToolUse hook. | yes |

Upgrading from v0.4.1? Run codehere memory init once — it migrates CONTEXT/HANDOVER/PROMPTS into the new layout and leaves symlinks at the old paths so back-compat holds. --dry-run shows what would move first.

What you see when you delegate a task

codehere start opens http://127.0.0.1:3773. Pick an agent, type a task, hit Assign. codehere:

1. Spawns the agent with the right headless flags
2. Streams the steps back as readable progress · "Read src/auth.ts · Edit src/auth.ts · Run npm test"
3. For Claude Code tasks: routes every tool call through the codehere safety hook — you see "🛡 5 safe · 0 blocked" grow live. For Codex / Aider / OpenCode / Gemini tasks: emits the agent's native event stream (no per-tool blocking yet)
4. On completion, hands you a Final report: files changed with +/- lines, trust score per file, test pass/fail, token usage

Claude Code tool calls are logged to ~/.codehere/audit/hook-events.jsonl; spawned-task lifecycle (any adapter) is logged to ~/.codehere/sessions.jsonl. Open-source MIT. Node 20+.

Just the safety hook (no agents required)

If you only want the audit-and-block layer for AI tools you already use:

codehere hook install   # activates the PreToolUse hook in your global ~/.claude/settings.json
codehere trust .        # static trust scan of the current directory
codehere report         # generates a shareable markdown audit report
codehere status         # quick dashboard · sessions, blocks, trust trends

The hook intercepts every Bash, Edit, Write, MultiEdit, and NotebookEdit call from any Claude Code session running on your machine, runs it through the trust-scorer pattern bank in under 5 ms, blocks anything matching the destructive / credential / injection patterns, and appends every decision to an append-only JSONL audit log at ~/.codehere/audit/. Codex, Aider, OpenCode, and Gemini adapters spawn through their native CLIs and emit to ~/.codehere/sessions.jsonl with per-tool tracing via the cross-vendor mirror hook.

Memory · F3 (v0.6)

Once you've run codehere init in a project, every spawned agent — Claude Code, Codex, Aider, OpenCode, or Gemini — automatically reads the project's memory on entry. The agent starts warm with the briefing, recent lessons, and the most-referenced symbols in your codebase, instead of cold-grepping every session.

What gets injected, in priority order:

1. .codehere/AGENTS.md — your project briefing (conventions, style, constraints)
2. .codehere/memory/working/session.md — what's in flight right now (per-machine, gitignored)
3. .codehere/memory/semantic/lessons.jsonl — graduated project-wide lessons
4. .codehere/memory/episodic/repo_map.json — top-N most-referenced symbols (run codehere memory repo-map to build / refresh)

The injection is token-budget-aware (default ~3000 tokens, drops lower-priority sections first to fit; AGENTS.md is never dropped). Pass --no-memory-prefix if you want the bare prompt for a one-off task.

Inspect what would inject before spawning anything:

codehere memory show injection

Add a lesson so future spawns learn from it:

codehere memory graduate --add "auth tests live alongside source files"

See everything codehere has accumulated:

codehere memory show              # one-line summary per layer
codehere memory show semantic     # numbered lesson list
codehere memory show episodic     # session count + top symbols
codehere memory show protocols    # safety patterns by category

Other memory commands:

• codehere memory init — migrate the v0.4.1 layout (CONTEXT.md / HANDOVER.md / PROMPTS.md) into the F3 layout (one shot, leaves back-compat symlinks; --dry-run previews)
• codehere memory repo-map [--rebuild] — build the symbol map; currently TS-native MVP
• codehere protocols export [--rebuild] — write the trust-scorer pattern bank to .codehere/protocols/hook_patterns.json for inspection / cross-tool ingestion

Going deeper

For technical readers — the living documents that describe codehere as a system, not just a CLI:

| Doc | What it is | |---|---| | docs/decisions/ | ADR registry — every locked architectural decision (audit-first moat, supervisor-agent positioning, local-first, F3 memory layout, generic-CLI adapter, ...) numbered, dated, with rejected alternatives + rollback triggers | | docs/THREAT_MODEL.md | Every attack surface, current mitigation, residual risk, planned hardening — npm supply chain, hook bypass, symlink redirect, audit log tampering, MCP server, prompt injection | | docs/CAPABILITIES.md | Honest matrix of what each adapter can and cannot do today — Claude Code, Codex, Aider, OpenCode, Gemini, Generic CLI — across spawn, stream, per-tool block, audit, F3 memory, auth | | agent/REPO_MAP.md | One-line-per-file index of the 54 source files with their top-level exports — generated, regenerated via npm run repomap after renames |

Commands

codehere start              · launch the task intake web UI at :3773
codehere task <prompt>      · spawn a task from the CLI (requires `start` running)
codehere kill <sessionId>   · kill a running task
codehere serve              · start as MCP server for Claude Desktop, Cursor, etc.
codehere status             · dashboard · sessions, blocked calls, audit trends
codehere trust [path]       · static trust scan · score 0-100, grade A-F
codehere report             · generate a shareable markdown audit report
codehere hook               · install/uninstall/inspect the PreToolUse safety hook
codehere permission         · manage this folder's allow-list (skip false-positive blocks)
codehere budget             · daily-spend ceiling · `set <usd>` blocks paid spawns at the cap
codehere narrator           · customize the PM narrator prompt (~/.codehere/narrator-prompt.md)
codehere setup              · interactive first-run setup wizard
codehere config             · manage configuration and preferences
codehere health             · system health check
codehere help               · show help (use --all for hidden commands)
codehere completion <shell> · generate bash/zsh/fish completion script
codehere scan-tool          · internal · used by the hook system, not by users

codehere --help for full options on each. codehere status --weekly produces a shareable 7-day agent-activity recap. codehere status --export jsonl > audit.jsonl exports the raw audit feed.

What it catches

The trust scorer + safety hook detect ~36 patterns across:

• SQL injection · XSS · command injection · path traversal
• Hardcoded secrets · API keys · weak crypto · JWT bypass
• Eval injection · prompt injection · credential theft
• Destructive shell operations · supply-chain patterns

Every blocked call is logged with the reason; every allowed call is logged with the trust score. Pattern bank lives in agent/src/infrastructure/security/trust-scorer.ts.

MCP server

codehere serve

Exposes 4 read-only tools to any MCP client (Claude Desktop, Cursor, Zed, Continue, Cline, etc.):

• codehere_trust · score a file or code snippet
• codehere_scan · scan text for injection / threat patterns
• codehere_review · scan a directory and return riskiest files
• codehere_audit · read the local hook audit log

codehere serve --show-config prints the JSON block to paste into Claude Desktop's MCP settings.

Architecture, story, and contribution

For depth beyond this README:

• docs/STRATEGIC_VISION.md · 20-year invariants + v4 positioning (individual-tier vendor-neutral) · figures in docs/figures/
• docs/PRD.md · master decision document · features, architecture, roadmap
• docs/SECURITY_AUDIT_2026-05-01.md · first-party security audit · OWASP Top 10 + STRIDE · 0 critical / 0 high · 2 medium fixed inline · methodology disclosed · reproducible
• docs/archive/ · earlier living docs (CODEHERE spec, EXPERIENCE story, AUDIT) preserved for history
• CONTRIBUTING.md · how to contribute · setup, commit discipline, testing philosophy
• SECURITY.md · responsible disclosure · [email protected]
• CODE_OF_CONDUCT.md · community standards
• CHANGELOG.md · per-version release notes

Requirements

• Node.js 20+ (pinned in .nvmrc and engines.node)
• macOS or Linux · Windows via WSL works for development
• Optional but recommended: at least one supported agent (Claude Code, Codex, Aider, OpenCode, or Gemini) installed before running codehere start

License

MIT · see LICENSE.