▄    █                               █  ▀▀█      ▀
 ▄▄█▄▄  █ ▄▄    ▄ ▄▄   ▄▄▄    ▄▄▄    ▄▄▄█    █    ▄▄▄    ▄ ▄▄    ▄▄▄
   █    █▀  █   █▀  ▀ █▀  █  ▀   █  █▀ ▀█    █      █    █▀  █  █▀  █
   █    █   █   █     █▀▀▀▀  ▄▀▀▀█  █   █    █      █    █   █  █▀▀▀▀
   ▀▄▄  █   █   █     ▀█▄▄▀  ▀▄▄▀█  ▀█▄██    ▀▄▄  ▄▄█▄▄  █   █  ▀█▄▄▀

        ·──────────────────────────────────────────────────────·
        Portable memory for agentic coding.
        Any agent resumes where the last one left off.

Portable memory & provenance for agentic coding. Switch tools, switch machines, never lose the thread.

Claude · Codex · Cursor · Kimi · OpenCode · ANY CLI

---

What is Threadline?

Threadline is the tool-neutral continuity layer for agentic coding. When an agent stops, runs out of context, or you switch from Claude Code to Codex (or to another machine), the state of what was being done and why normally evaporates — it's trapped inside each tool's private session store. Threadline sits above every tool and captures that state as a portable, git-aware handoff any agent can resume from.

It also normalizes agent config across runtimes and keeps project state outside your git history — but those serve the headline: never losing the thread.

Why Threadline Exists

Developers now switch between multiple AI coding tools — Claude Code for deep reasoning, Codex for agentic tasks, Cursor for IDE work, Kimi for long context. The expensive problem isn't config formatting; it's continuity:

1. State loss. Hit a context wall or switch tools mid-task and the agent's working memory — branch, diff, decisions, what's verified — is gone. You re-explain everything.
2. No cross-tool replay. Work started in one agent can't be picked up by another. Each tool is an island.
3. No provenance. As agents touch real code, "what was the agent configured with when it made this change?" has no answer.

Threadline solves continuity first: auto-captured, git-grounded handoffs that replay into any runtime. Config sync and zero-clutter project state come along for free.

Features

• Git-Grounded Handoffs — Every handoff captures real state: branch, HEAD, ahead/behind, uncommitted files, recent commits. Not a stub you fill in by hand.
• Auto-Capture — threadline watch installs hooks so a handoff is written automatically when a session ends or context is about to compact. No discipline required.
• Cross-Tool Resume — threadline resume emits an agent-replayable brief, framed for the target tool (--format claude|codex). Start in Claude Code, continue in Codex.
• Multi-Runtime Setup — Configure Claude Code, Codex, Cursor, Kimi, OpenCode, or any generic CLI in one command.
• Zero Repo Clutter — Project profiles live under ~/.local/share/threadline/ by default. Your git history stays clean.
• Automatic Stack Detection — Detects Node.js, React, Vite, Next.js, TypeScript, Firebase, and more. Recommends only the skills you need.
• Portable Skills — Write skills once. Threadline adapts them for each runtime's expected format.
• Atomic & Safe — All writes are atomic, idempotent, and backed up. Merge mode preserves your existing config. Replace mode requires an explicit --yes.

Quick Start

One-Line Setup

npx threadline-cli setup

This launches an interactive onboarding that scans your system, detects installed AI runtimes, and asks which ones to configure.

The Continuity Loop

# 1. Turn on auto-capture once (installs Claude Code session hooks).
npx threadline-cli watch

# 2. Work normally. On session end / pre-compaction, a git-grounded
#    handoff is written automatically. Or capture one yourself:
npx threadline-cli handoff create --auto

# 3. Switch tools, switch machines, come back next week — resume.
#    Pipe the brief straight into another agent:
npx threadline-cli handoff resume --latest --format codex

resume prints an agent-replayable brief: the summary, exactly where the code was left (branch, diff, unpushed commits, changed files), and the next actions — ground truth, not vibes.

Non-Interactive / CI Mode

npx threadline-cli setup --replace --yes --runtimes claude,codex
npx threadline-cli init --path ./my-project --local
npx threadline-cli detect --path ./my-project --json

Generic CLI Support

Threadline works with tools it has never heard of:

npx threadline-cli setup --merge --runtimes gemini,pi,my-custom-cli

Installation

Requires Node.js 20 or later.

# Run without installing
npx threadline-cli setup

# Or install globally (binary stays `threadline`)
npm install -g threadline-cli
threadline setup

How It Works

Runtime Adapters

Each AI tool gets a normalized adapter. Threadline speaks their config language so you don't have to.

Runtime	What Threadline Manages
Claude Code	Skills, slash commands, project hooks, local settings
Codex	Skills, config.toml, MCP configuration, agent roles
Cursor	Skills, .cursor/config.toml, rules files
Kimi	Skills, commands, .kimi/config.toml
OpenCode	Skills, commands, .opencode/config.toml
Any CLI	Generic adapter creates ~/.<cli>/skills and ~/.<cli>/commands

Project Detection

Threadline identifies a project by its git remote URL (or git root if no remote exists) and generates a stable 12-character hash. The same repo resolves to the same profile across machines.

$ threadline detect --json
{
  "id": "a1b2c3d4e5f6",
  "name": "my-app",
  "root": "/Users/you/code/my-app",
  "remote": "git@github.com:you/my-app.git",
  "packageManager": "npm",
  "stacks": ["node", "typescript", "react", "vite"],
  "recommendedPresets": ["minimal", "fullstack-js", "react-vite"]
}

XDG Directory Layout

~/.config/threadline/       # Human-editable config, dotfiles-friendly
~/.local/share/threadline/  # Generated state, profiles, handoffs, indexes
~/.cache/threadline/        # Temporary and cache data

Local-First Project State

~/.local/share/threadline/projects/<project-id>/
└── workspaces/
    └── <workspace-id>/
        ├── project-profile.json
        ├── generated/
        │   ├── AGENTS.generated.md
        │   ├── codex.generated.toml
        │   └── claude.generated.json
        ├── rag/
        ├── handoffs/
        ├── knowledge-graph/
        └── learnings/

Commands

Command	Purpose
threadline setup	Install or sync user-level runtime configuration
threadline init	Detect project and generate a project profile
threadline detect	Print project detection results
threadline skills list	List all available skills from the registry
threadline skills recommend	Recommend skills for the current project stack
threadline index	Build a manifest-based RAG index
threadline handoff create	Write a git-grounded handoff (--auto to derive from git)
threadline handoff list	List all handoffs, newest first
threadline handoff resume	Print an agent-replayable brief (--latest, --format claude|codex)
threadline watch / unwatch	Install / remove auto-capture session hooks
threadline tools list	Show available modern CLI tool integrations

See docs/commands.md for full command reference.

Safety Model

Threadline never needs to overwrite your setup to become useful.

Mode	Behavior
merge (default)	Adds missing managed sections. Preserves everything else.
adopt	Inspects your current setup and writes an adoption report.
replace	Replaces Threadline-managed files. Requires --yes.

Project setup is local by default:

Mode	Behavior
local	Stores profile under XDG state. Zero git changes.
repo	Materializes files into the repo. Intentionally git-visible.

Documentation

• Architecture — Design principles, project identity, and state layout.
• Commands — Full CLI reference.
• Skills — How the skill registry and presets work.
• RAG & Kimi — Retrieval-augmented generation and Kimi integration.
• Handoffs & Obsidian — Session handoffs and Obsidian vault output.
• Runtime Adapters — Adapter interface for adding new runtimes.
• Roadmap — What's shipped and what's next.

Status

Threadline is in early alpha. The continuity layer works today: git-grounded handoff capture, handoff list/resume (by id or --latest), agent-replayable briefs with per-tool framing (--format claude|codex), and auto-capture via watch/unwatch session hooks on Claude Code. The CLI also supports project detection, skill listing/recommendation/install, multi-runtime setup (merge/adopt/guarded replace), and manifest-based indexing. All writes are atomic, idempotent, backed up, reject relative XDG state paths, and fail closed on conflicting unmanaged Codex TOML tables.

Per-runtime auto-capture beyond Claude, the handoff timeline, team handoffs, LightRAG embeddings, and a verifiable skill lockfile are staged for follow-up releases.

License

MIT — see LICENSE.

Acknowledgments

Threadline is inspired by the frustration of maintaining five different agent configs across dozens of repos. Built for developers who treat AI tools as a toolchain, not a vendor lock-in.