codehere 0.2.2 → 0.3.0-rc.1

package/README.md

@@ -1,13 +1,15 @@
 # codehere
 
-> Know what your AI agent actually did — before your tech lead asks.
+> **Every AI action, traced. Every agent, verified.**
 
 [![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](../LICENSE)
+[![Tests](https://img.shields.io/badge/tests-216%2F216-brightgreen)]()
+[![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)]()
 
-codehere scans every AI write before it touches your codebase. Works with Claude Code, Cursor, Codex — any AI coding agent.
+codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks the right specialist (Claude Code, Codex, Aider, or OpenCode), wraps every action in the safety hook, audits everything, and hands you a plain-English report with a **trust score on every file changed**.
 
-**Safety features need no API key. AI features work with Anthropic or OpenAI.**
+One manager, many specialists, everything traceable.
 
 ## Install
 
@@ -15,84 +17,87 @@ codehere scans every AI write before it touches your codebase. Works with Claude
 npm install -g codehere
 ```
 
-## 30 seconds to safer AI coding
+Requires Node.js 20+. Open-source MIT.
 
-```bash
-# Activate the safety hook — every AI write gets scanned
-codehere hook install
+## Quick start
+
+### Delegate a task to an AI agent
+
+Make sure at least one of the four supported agents is installed:
+
+| Agent | Install |
+|---|---|
+| Claude Code | `npm install -g @anthropic-ai/claude-code` |
+| Codex CLI | `npm install -g @openai/codex` |
+| Aider | `brew install aider` |
+| OpenCode | `curl -fsSL https://opencode.ai/install \| bash` |
 
-# See what the scanner finds
-codehere trust .
+Then:
 
-# Get a shareable audit report
-codehere report
+```bash
+codehere start          # opens http://127.0.0.1:3773 in your browser
 ```
 
-That's it. Every `Bash`, `Edit`, `Write`, and `MultiEdit` call from your AI assistant now goes through a 60+ pattern security scan in under 5ms. Dangerous calls get blocked with a reason. Clean calls execute normally.
+You'll see:
 
-## What it catches
+- **Today's activity** · "47 AI actions · 3 blocked · avg trust 91 · 4 agents"
+- **A task intake** with three starter prompts you can click
+- **A cwd field** pre-filled with where you ran `codehere start`
+- **An agent dropdown** showing which of the four are installed (and a one-click Install button for the others)
 
-SQL injection, XSS, command injection, hardcoded secrets, path traversal, SSRF, weak crypto, JWT bypass, eval injection, open redirects, prompt injection, credential theft, destructive operations, supply chain patterns.
+Pick an agent, type a task, hit **Assign**. codehere:
 
-## AI-powered commands
+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. Runs every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live
+4. On completion, hands you a **Final report**: files changed with `+/-` lines, trust score per file, test pass/fail, token usage
 
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY
+Everything is logged to `~/.codehere/audit/`. One feed, every agent, every action.
 
-codehere index                          # build codebase index (once)
-codehere ask "how does auth work?"      # ask about your code
-codehere explain src/api.ts             # explain a file
-codehere fix src/api.ts "add validation"  # AI fix with safety check
-codehere plan "refactor auth to JWT"    # plan complex tasks
-```
+### Just the safety hook (no agents required)
 
-Or just type what you want:
+If you only want the audit-and-block layer for AI tools you already use:
 
 ```bash
-codehere "what vulnerabilities does server.js have"
-codehere "explain the auth flow"
+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
 ```
 
-codehere routes your query to the right tool automatically.
+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 a tamper-evident JSONL audit log.
 
-## Interactive REPL
+## Commands
 
-```bash
-codehere    # launches the REPL
+```
+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 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
 ```
 
-- Type anything — plain language routes to the right command
-- Type `/` to see all 27 commands with descriptions
-- Arrow keys navigate the palette, Tab completes
-- `trust .`, `status`, `explain src/auth.ts` work with or without `/`
+`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.
 
-## Safety commands (no API key)
+## What it catches
 
-| Command | What it does |
-|---|---|
-| `codehere hook install` | Activate pre-execution safety hook |
-| `codehere trust [path]` | Security scan — score 0-100, grade A-F |
-| `codehere trust --ci` | Exit 1 on critical findings (for CI pipelines) |
-| `codehere report` | Markdown audit report (shareable) |
-| `codehere report --simple` | Plain English for non-technical readers |
-| `codehere status` | Dashboard: scans, blocks, recent activity |
-| `codehere health` | System health check |
-| `codehere serve` | Start as MCP server for Claude Desktop / Cursor |
+The trust scorer + safety hook detect 60+ patterns across:
 
-## How the hook works
+- SQL injection · XSS · command injection · path traversal · SSRF
+- Hardcoded secrets · weak crypto · JWT bypass · open redirects
+- Eval injection · prompt injection · credential theft
+- Destructive operations · supply-chain patterns
 
-```
-Your AI assistant → runs a command
-         ↓
-codehere intercepts (PreToolUse hook)
-         ↓
-60+ pattern scan in < 5ms
-         ↓
-Clean? → executes normally
-Dangerous? → blocked with reason
-         ↓
-Everything logged to ~/.codehere/audit/
-```
+Every blocked call is logged with the reason; every allowed call is logged with the trust score.
 
 ## MCP server
 
@@ -100,18 +105,33 @@ Everything logged to ~/.codehere/audit/
 codehere serve
 ```
 
-Exposes 4 tools to any MCP client (Claude Desktop, Cursor, etc.):
-- `codehere_trust` — score a file or snippet
-- `codehere_scan` — scan text for threats
-- `codehere_review` — find riskiest files
-- `codehere_audit` — read the audit log
+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:
+
+- **[CODEHERE.md](../CODEHERE.md)** · product spec · positioning, six-ring adoption funnel, F0–F6 foundations, defensibility, GTM, revenue model
+- **[EXPERIENCE.md](../EXPERIENCE.md)** · the human story · how engineering teams, CISOs, and regulated-industry buyers adopt codehere
+- **[AUDIT.md](../AUDIT.md)** · pre-publish audit report · methodology, findings, remediation
+- **[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 18+
-- For AI commands: `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
-- For safety features: nothing — works out of the box
+- **Node.js 20+** (pinned in `.nvmrc` and `engines.node`)
+- **macOS or Linux** · Windows via WSL works for development; native Windows is on the v0.4 roadmap
+- **Optional but recommended:** at least one supported agent (Claude Code, Codex, Aider, or OpenCode) installed before running `codehere start`
 
 ## License
 
-MIT
+MIT · see [LICENSE](../LICENSE).

package/dist/domain/entities/task.js

@@ -13,7 +13,7 @@ export var TaskMode;
     TaskMode["SUGGEST"] = "suggest";
     TaskMode["PLAN"] = "plan";
     TaskMode["RUN"] = "run";
-    TaskMode["REVIEW"] = "review"; // HITL mode - inspection/approval
+    TaskMode["REVIEW"] = "review";
 })(TaskMode || (TaskMode = {}));
 /**
  * Task Status - Current lifecycle state
@@ -28,7 +28,7 @@ export var TaskStatus;
     TaskStatus["NEEDS_REVIEW"] = "needs_review";
     TaskStatus["APPROVED"] = "approved";
     TaskStatus["REJECTED"] = "rejected";
-    TaskStatus["CANCELLED"] = "cancelled"; // User cancelled task
+    TaskStatus["CANCELLED"] = "cancelled";
 })(TaskStatus || (TaskStatus = {}));
 /**
  * Risk Tier - Risk level for operation
@@ -37,7 +37,7 @@ export var RiskTier;
 (function (RiskTier) {
     RiskTier["T1"] = "t1";
     RiskTier["T2"] = "t2";
-    RiskTier["T3"] = "t3"; // High risk - explicit warning + confirmation
+    RiskTier["T3"] = "t3";
 })(RiskTier || (RiskTier = {}));
 /**
  * Environment Mode - Data access boundaries
@@ -46,7 +46,7 @@ export var EnvironmentMode;
 (function (EnvironmentMode) {
     EnvironmentMode["LOCAL"] = "local";
     EnvironmentMode["ORG"] = "org";
-    EnvironmentMode["INTERNET"] = "internet"; // Full internet access (explicit opt-in)
+    EnvironmentMode["INTERNET"] = "internet";
 })(EnvironmentMode || (EnvironmentMode = {}));
 /**
  * Review Status

package/dist/error-handler.js

@@ -101,11 +101,7 @@ export function isRetryable(error) {
     if (errorType === ErrorType.RATE_LIMIT) {
         return false;
     }
-    return [
-        ErrorType.RETRYABLE,
-        ErrorType.NETWORK,
-        ErrorType.API_ERROR,
-    ].includes(errorType);
+    return [ErrorType.RETRYABLE, ErrorType.NETWORK, ErrorType.API_ERROR].includes(errorType);
 }
 /**
  * Calculate exponential backoff delay
@@ -120,7 +116,7 @@ export function calculateBackoff(attempt, baseDelay = 1000, maxDelay = 60000) {
  * Retry with exponential backoff
  */
 export async function retryWithBackoff(operation, options = {}) {
-    const { maxRetries = 5, baseDelay = 1000, maxDelay = 60000, operationName = 'operation', onRetry, } = options;
+    const { maxRetries = 5, baseDelay = 1000, maxDelay = 60000, operationName = 'operation', onRetry } = options;
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
@@ -148,7 +144,7 @@ export async function retryWithBackoff(operation, options = {}) {
             if (onRetry) {
                 onRetry(attempt + 1, error);
             }
-            await new Promise(resolve => setTimeout(resolve, delay));
+            await new Promise((resolve) => setTimeout(resolve, delay));
         }
     }
     // All retries exhausted
@@ -172,8 +168,7 @@ export class CircuitBreaker {
     lastFailureTime = 0;
     state = 'CLOSED';
     constructor(threshold = 5, timeout = 60000, // 1 minute
-    resetTimeout = 30000 // 30 seconds
-    ) {
+    resetTimeout = 30000) {
         this.threshold = threshold;
         this.timeout = timeout;
         this.resetTimeout = resetTimeout;