A lightweight shared context layer that lets multiple coding agents (currently Claude Code and Codex) maintain continuity across sessions without manual copy-paste.

Built first to solve my own workflow: a local-first, solo/small-team setup where I switch between agents on the same codebase and want shared task state without another service to operate. If your constraints look similar, it may be useful as a starting point.

Gemini CLI is not packaged here as a first-class integration yet, but the underlying bootstrap model is compatible with the same style of wrapper/context-file setup.

• Task-centric context: One Obsidian-compatible markdown file per task, containing goals, decisions, current state, and session logs
• Automatic context injection: SessionStart hooks inject relevant task context when an agent starts, based on git branch matching
• Cross-agent handoff: Session transcripts (JSONL) are registered on tasks, enabling agents to read each other's last messages
• Lifecycle management: Tasks flow through in-progress -> paused -> done/abandoned with automatic stale-task detection
• Obsidian-native: Wikilinks, backlinks, and Graph View work out of the box for navigating decisions across tasks

• Not a memory system. ctx does not store user preferences, learned patterns, or long-term knowledge. It tracks task state — what was decided, what was done, what's next. Memory belongs to the agent; context belongs to the task.
• Not infrastructure. No server, no database, no daemon. It's shell scripts composing git, jq, and flat files. If you delete the repo, you lose a CLI. The vault is just markdown.
• Not a communication protocol. Agents don't message each other. They read the same task file and each other's session transcripts. The coordination model is a shared document, not a message bus.

settings.json hooks ──> hooks/context-start.sh ──> scripts/bootstrap.sh
                                                       │
codex alias ─────────> scripts/codex-bootstrap.sh ─────┤
                                                       │
                                                  scripts/resolve.sh
                                                       │
                                               $CTX_VAULT (Obsidian vault)
                                               ├── _active.md
                                               ├── _categories.md
                                               └── tasks/
                                                   ├── my-feature.md
                                                   └── ...

git clone https://github.com/leonhartX/ctx.git ~/ctx
cd ~/ctx
./setup.sh

Follow the printed instructions to configure your shell, Claude Code hooks, and Codex alias.

• bash, jq, python3, git
• Claude Code and/or Codex CLI
• Obsidian — strongly recommended. The vault works as plain markdown, but Graph View, backlink navigation, and full-text search across decisions are a large part of the value. Without Obsidian it's a folder of .md files; with it, it's a navigable knowledge base.
• (Optional) gh CLI for PR merge detection in ctx gc

ctx latest [-n count] [task-name]   # Show last agent messages from transcripts
ctx lint                            # Integrity checks
ctx decision [--task TASK] <text>   # Quick decision note
ctx note [--task TASK] <text>       # Same as decision
ctx attach-current <task-name>      # Attach session transcript to a task
ctx pause <task-name>               # Pause a task
ctx resume <task-name>              # Resume a paused task
ctx done <task-name>                # Mark task complete
ctx gc-cron                         # Automated maintenance (for cron/launchd)

ctx save          # Save session summary to task log
ctx new <name>    # Create a new task
ctx find <kw>     # Search tasks by keyword
ctx status        # Show system status
ctx auto-save     # Batch-save unsaved transcripts
ctx gc            # Full cleanup with semantic checks

1. Session starts: Hook calls bootstrap.sh, which resolves the current branch to a task via _active.md, builds a lightweight summary (~150 tokens), and injects it as additionalContext
2. During session: Commits are auto-logged to the task file. First file edit registers the session transcript
3. Session ends: User runs ctx save to write a semantic summary, update decisions, and record state
4. Next session (same or different agent): Bootstrap injects the saved context plus the last messages from other agents' transcripts

---
task: my-feature
branch: feat/my-feature
repo: my-repo
status: in-progress
tags: [auth, api]
transcripts:
  - agent: claude-code
    date: 2025-01-15
    path: ~/.claude/projects/.../session.jsonl
---

# my-feature

## Goal
One-line objective

## Current State
Latest progress summary

## Decisions
- 2025-01-15: Use JWT for auth. [[mod/auth]] [[aspect/security]]

## Pending
- [codex 2025-01-15] Review the auth middleware implementation

## Log
### 2025-01-15 14:30 claude-code
**Objective**: Implement auth middleware
**Done**: ...

MIT