Threadnote

Stop explaining the same codebase to every coding agent.

Threadnote 5 helps your next agent session pick up the decisions and unfinished work from the last one, with current
code evidence to check against. It works across catalog-supported agent surfaces
without making one chat history or vendor memory the source of truth.

Personal work stays local. Exact files in the current worktree remain authoritative. Only durable knowledge or
reusable artifacts—including verified procedures—that you explicitly review and publish cross into a Git-backed team
store.

Website: https://threadnote.io/

Documentation: https://threadnote.io/docs/

Supported agents: https://threadnote.io/agents/

What’s new: https://threadnote.io/whats-new/

The Threadnote 5 workflow

1. Start with a Context Brief. The installed agent guidance automatically loads a bounded set of relevant
   decisions, active handoffs, compatible procedures, and current-code evidence with provenance, freshness, and
   visible gaps.
2. Verify the live code. Use exact local files and Threadnote’s code graph for current relationships; historical
   context never overrides the worktree.
3. Review the Knowledge Delta. At meaningful closeout, the agent writes a private handoff and proposes decisions,
   constraints, verification, invalidated knowledge, and unresolved risks. Approve, edit, defer, or reject each
   candidate.
4. Share deliberately. Publish approved knowledge directly or materialize a provider-neutral Git proposal for the
   team’s normal review policy. Private handoffs and preferences stay local.
5. Keep context healthy. Review ownership and expiry, changed citations, contradictions, guidance drift, Context
   Check findings, and local content-free value reports without silent deletion or publication.

Threadnote is a self-contained executable. The local and Git-team workflow needs no separately installed runtime,
Python service, database server, hosted organization account, or background daemon.

Quick start

Install on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh

On Windows PowerShell:

irm https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.ps1 | iex

Then open the repository you want Threadnote to understand, choose a managed surface from the catalog, preview setup,
and apply the same plan:

cd /path/to/repository
threadnote agents list
threadnote setup <surface>
threadnote setup <surface> --apply

Setup initializes the local core, repository seed, selected catalog integration and declared hooks, current code graph,
doctor checks, and a real source-backed Context Brief using its built-in repository-orientation task. Preview does not
write; interrupted apply is resumable; undo is also preview-first and removes only unchanged setup-owned artifacts.

Once your agent restarts, give it a normal engineering task. The installed instructions and skills make Context Brief
and closeout part of the agent's normal lifecycle, so you do not need a special Threadnote prompt. Ask “What can I do
with Threadnote?” only when you want the optional state-aware guided tour.

For the complete cross-agent path, see Threadnote 5 context workflows and guided
two-agent activation. Team setup is covered by the sharing guide.
Existing users can follow the website guides for upgrading from Threadnote
4 or migrating from Threadnote
3.

Contributing

Contributions to the CLI, MCP server, Manager, website, documentation, tests, and agent workflows are welcome. Use the
Bun version pinned by packageManager in package.json, install dependencies, and run the narrowest
checks that cover your change:

bun install --frozen-lockfile
bun run typecheck
bun --bun vitest run <focused-test-file>

Read CONTRIBUTION.md before a substantial change. It covers Effect conventions, focused testing,
security boundaries, generated files, pull requests, and the exact-HEAD development runtime. The
private workspace guide explains package ownership, dependency checks, and selective Bazel CI.

License

Threadnote is licensed under AGPL-3.0-or-later. Model licenses are recorded separately in their manifests
and third-party notices.