Integration

Wire Lifeline into Claude Code, Cursor, Claude Desktop, and Gemini CLI via MCP — with auto-connect.

Lifeline has two sides, and the AI drives both:

Read on connect → MCP resource lifeline://project/context (or python -m lifeline context).
Write while working → MCP tools lifeline_append / lifeline_recontextualize (or python -m lifeline log).

MCP client (any of them)

Point the client at the stdio server. The server command is lifeline-mcp (installed by pip install lifeline-context); it reads the DB from LIFELINE_DB (default .lifeline/ledger.db). Set the env var the way your client config does — e.g. an "env" block in the JSON snippets below. At a shell directly:

LIFELINE_DB=.lifeline/ledger.db lifeline-mcp        # bash/zsh

$env:LIFELINE_DB=".lifeline/ledger.db"; lifeline-mcp    # PowerShell

Resource: lifeline://project/context — read it when opening the session.
Read tools (0.6): lifeline_context(query, thread, budget, line) — the context as a tool; lifeline_resume(thread) — where work stopped (read it after any compaction); lifeline_brief(task_or_thread, budget) — the scoped brief for a sub-agent; lifeline_recall(query).
Write tools: lifeline_append(kind, summary, body, …, thread, line), lifeline_recontextualize(parent_id, summary, body, …), lifeline_checkpoint(thread, done, next, blocked, tried, goal). Routed by the project's write policy (.lifeline/policy.json): direct (audited) | propose (HITL, the default) | deny — checkpoints are direct by default.
Server command: lifeline-mcp (or python -m lifeline.mcp_server from the repo root).
Named line: set LIFELINE_LINE=<name> instead of LIFELINE_DB — the server derives .lifeline/<name>.db (an explicit LIFELINE_DB always wins). Any tool also takes line="<name>" to reach another line of the same project (the mesh) without a second server.
Provider delivery (Law #4): lifeline context --format anthropic|openai|gemini [--budget-tokens N] prints the same context in the provider's system-message envelope — the stable prefix carries cache_control for Claude; OpenAI and Gemini get it first for prefix caching.

Per-client snippets (copy-and-paste)

Claude Code — already reads the project's .mcp.json automatically. Without it: claude mcp add lifeline -- lifeline-mcp.

Cursor — .cursor/mcp.json (at the project root):

{ "mcpServers": { "lifeline": { "command": "lifeline-mcp", "env": { "LIFELINE_DB": ".lifeline/ledger.db" } } } }

Claude Desktop — claude_desktop_config.json (use an ABSOLUTE path — the cwd differs):

{ "mcpServers": { "lifeline": { "command": "lifeline-mcp", "env": { "LIFELINE_DB": "C:/path/to/project/.lifeline/ledger.db" } } } }

Gemini CLI — ~/.gemini/settings.json:

{ "mcpServers": { "lifeline": { "command": "lifeline-mcp", "env": { "LIFELINE_DB": ".lifeline/ledger.db" } } } }

WEB chat apps (claude.ai, ChatGPT) do not belong here — they require a remote server + OAuth (see docs/MCP_REMOTE.md). These snippets are for dev/CLI/IDE clients (stdio, local).

Verification status (honest): Claude Code (stdio, .mcp.json, named lines) and the remote path (claude.ai connector via OAuth RS mode: 401 without a token, 200 with a valid JWT, consent page) are validated live on this very repo. The Cursor / Claude Desktop / Gemini CLI snippets follow each client's documented config format but haven't been exercised end-to-end by us yet — if you run one, tell us what happened (works-fine reports are as valuable as bugs).

Capture while you work (close the loop automatically)

Local, zero-LLM: lifeline capture drafts proposals from your recent git commit messages (the commit body is the why; commits without one are skipped). Run it at the end of a work session; curate with lifeline review.
Team, on GitHub: the Lifeline GitHub App drafts proposals from every merged PR's human-written text (description + reviews) into the hub's Review queue — edit, approve or reject there. Opt-in per repo; PRs with no written rationale are skipped silently.

Auto-connect in Claude Code (SessionStart hook)

One command (0.6): lifeline install-hooks claude-code writes (or merges, idempotently) a SessionStart hook into .claude/settings.json with matcher startup|resume|compact — the context and the Resume section enter the session on startup, on resume, and after each compaction. --local writes settings.local.json instead. By hand, it is:

{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup|resume|compact",
        "hooks": [ { "type": "command", "command": "python -m lifeline context" } ] }
    ]
  }
}

Discipline: making every AI update the line (0.6)

A reminder in a prompt fades after compaction. What works is a check at the boundary where the AI tries to stop, and a net underneath. Three boundaries, three mechanisms — all lifeline guard:

Boundary	Command	What happens
End of an agent session	`lifeline install-hooks claude-code` → `Stop` hook runs `lifeline guard --session`	if the work tree changed and the line got no checkpoint/entry since the session start, the stop is blocked once with the instruction; a second stop passes
End of a sprint / before sharing	`lifeline install-hooks git` → `pre-push` runs `lifeline guard --git`	code commits after the last ledger entry and nothing recorded → the push fails (bypass: `--no-verify`)
Any client, MCP or not	`lifeline install-rules`	the loop, in four lines, in `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/lifeline.mdc`, `.github/copilot-instructions.md` (idempotent; existing files get the section appended)

The net: lifeline capture drafts proposals from commit messages when the AI forgot to write. The measure: lifeline audit --since 7d (who wrote) and lifeline exam (freshness). The honest limit: a guard makes the AI write; only curation (lifeline resume, review) makes it worth reading.

Write policy (who may write directly)

.lifeline/policy.json is project config (versioned; the .gitignore re-includes it). Without it, checkpoint is direct and every other AI write is a proposal. Grant a trusted agent more:

lifeline policy --init --agent claude-code     # note/feature/fix/checkpoint direct for that agent
lifeline audit --since 7d                      # what entered directly (status 'auto'), with ids

A wrong direct write is never edited — supersede it with a correction (lifeline_recontextualize).

Without a hook, the minimal convention (in CLAUDE.md) is: on opening, run python -m lifeline context and read it before acting. When making any decision/feature/fix, append — that way the next AI (or you tomorrow) connects and already knows.

Lifeline — MIT licensed · Edit on GitHub ← Back to the lifeline