# codehere

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

[![npm](https://img.shields.io/npm/v/codehere)](https://www.npmjs.com/package/codehere)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](../LICENSE)
[![Internal tests](https://img.shields.io/badge/internal_tests-1200%2F1200-brightgreen)]()
[![Honest status](https://img.shields.io/badge/v0.7--honest--reframe-2026--05--19-blue)](../docs/TRUTHFUL_STATE_2026-05-19.md)

**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`](../docs/TRUTHFUL_STATE_2026-05-19.md) for the verified / assumed / unverified classification of every surface.

The enterprise tier is owned by [OpenAI Frontier](https://openai.com/index/introducing-openai-frontier/) (8-14 weeks of deploy prereqs, sales-team gated) and [Anthropic Cowork](https://www.anthropic.com/product/claude-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`](../docs/STRATEGIC_VISION.md) Appendix C and [`docs/figures/positioning-matrix.svg`](../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](../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/](../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:

```bash
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:
```bash
codehere memory show injection
```

**Add a lesson** so future spawns learn from it:
```bash
codehere memory graduate --add "auth tests live alongside source files"
```

**See everything codehere has accumulated:**
```bash
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/`](../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`](../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`](../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`](./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

```bash
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](../docs/STRATEGIC_VISION.md)** · 20-year invariants + v4 positioning (individual-tier vendor-neutral) · figures in `docs/figures/`
- **[docs/PRD.md](../docs/PRD.md)** · master decision document · features, architecture, roadmap
- **[docs/SECURITY_AUDIT_2026-05-01.md](../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/](../docs/archive/)** · earlier living docs (CODEHERE spec, EXPERIENCE story, AUDIT) preserved for history
- **[CONTRIBUTING.md](../CONTRIBUTING.md)** · how to contribute · setup, commit discipline, testing philosophy
- **[SECURITY.md](../SECURITY.md)** · responsible disclosure · `security@codehere.uk`
- **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** · community standards
- **[CHANGELOG.md](../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](../LICENSE).