Documentation

ThreadPort records what happens during a development task and hands it to the next AI agent as a short, sourced context pack. This page covers the CLI (version 0.5 and later) and the VS Code extension.

Install

You need Node.js 24 or newer and npm. Git is recommended: without it, ThreadPort still works but cannot take snapshots or tie verification to a commit.

npm install -g threadport
threadport --version
threadport doctor

doctor shows your Node version, whether the project is initialized, and which agents (Claude Code, Codex) are installed.

Quick start

Run these from the root of the project you want to track.

threadport init
threadport new "Fix token rotation"
threadport task add "Write a concurrency test"
threadport decision "Keep token IDs in Redis" -r "Shared revocation"
threadport run claude

When Claude exits, record anything its interface did not expose, then hand off:

threadport note "The collision happens during simultaneous renewal"
threadport check npm test
threadport switch codex

Codex starts with the objective, the open task, the decision and the failing test. Commands work from any subdirectory of the project.

How it works

Session: One task with an objective. One session is active at a time; open and resume switch between them.
Records: Tasks, notes, errors, decisions, test results, constraints, relevant files and project memory. Each has an ID you can edit or delete.
Context pack: Markdown built from the session and the live Git state, ordered by priority and cut to a token budget. Every section names its source.
Runs: Each agent launch is recorded with its status and exit code. A run that stops unexpectedly is marked interrupted.

All of it lives in .threadport/threadport.sqlite inside your project. ThreadPort writes .threadport/.gitignore so Git ignores it.

Commands

Command	What it does
`init`	Initialize the project in the current directory.
`new "objective"`, `sessions`, `open <id>`, `resume <id>`	Create, list and reactivate sessions. `resume` also prints the context.
`rename`, `finish`, `delete`	Rename, finish or permanently delete a session.
`status`, `timeline`, `snapshot`	Show the active session, its events, or capture the Git state.
`task add`, `task done <id>`, `task list`	Track tasks.
`decision "title" -r "reason"`, `decisions`	Record and list decisions.
`note`, `error`, `constraint`, `memory`	Record notes, issues, constraints, and knowledge shared by every session.
`file <path>`, `files`, `artifact <path>`	Mark relevant files and artifacts; `files` also lists Git changes.
`record edit`, `record delete`	Correct or remove a record.
`check <cmd> [args]`, `test-result`, `command-log`	Run a command and save its result, or record one run elsewhere.
`summary`, `search "terms"`	Summarize the session, or search every session locally.
`context [--mode] [--explain]`	Preview the context pack and its token budget.
`run`, `switch`, `continue <agent>`	Launch an agent with the context, or resume its native session.
`verify`, `handoff`, `link`	Verify work, review a handoff, link a GitHub issue or pull request.
`export`, `import`	Move a session to another copy of the project.
`fork`, `compare`	Try several agents in separate Git worktrees and compare them.
`agents`, `doctor`, `config`	List agents, check the environment, change settings.
`hook`, `plugin`, `privacy`	Lifecycle hooks, custom agents, privacy audit and scrub.
`tui`, `serve`, `mcp`	Terminal menu, local HTTP API, MCP server.

Run threadport <command> --help for every option.

Context modes

Mode	Budget	Includes
`minimal`	500 tokens	Objective, high-priority items and a few events.
`standard`	1,500 tokens	Summary, memory, constraints, tasks, errors, decisions, tests, notes, files and Git state as space allows.
`deep`	4,000 tokens	The same, with more events and a filtered Git diff.
`full`	10,000 tokens	The same selection with a larger budget.

threadport context --mode deep --explain
threadport config set-default-mode deep

Token counts use cl100k_base as a reference and may differ from a given model's tokenizer. --explain lists the sources used and the sections that did not fit.

Running agents

run launches Claude Code or Codex in your terminal with the context file. switch does the same and records the handoff from the previous agent.

threadport run codex --structured
threadport status
threadport continue codex

--structured runs the agent without its interactive interface and records the commands, messages, errors and provider session ID from its JSON stream. continue then resumes that native session.

Automatic handoffs with hooks

threadport hook install claude
threadport hook install codex

These project-local hooks give the agent the context when it starts, record the files it edits, and write a summary when it stops. They never copy conversations, tool arguments or tool output. Codex asks you to trust new hooks with /hooks.

Verify and hand off

verify runs the check, test and build scripts of a Node project, or the commands in .threadport/config.json, and ties the result to the current Git state. Any file change makes the report stale.

threadport link issue https://github.com/owner/repo/issues/42
threadport verify
threadport handoff draft --out .threadport/handoff.md
threadport handoff save .threadport/handoff.md
threadport handoff show

Privacy

API keys, GitHub, GitLab, npm, Stripe, AWS, Google and Slack tokens, JWTs, Bearer headers, URL credentials, private keys and token= or password: values are redacted before storage and before any handoff. Detection is heuristic.
.env, .env.*, *.pem, *.key, credentials.json and secrets/** are excluded by default. Add patterns, one per line, in .threadportignore.
Snapshots store paths, not diff contents. A diff appears only in deep and full context.

threadport privacy audit --show-context
threadport privacy scrub

scrub applies current rules to data recorded before them.

Configuration

Project settings live in .threadport/config.json:

{
  "context": { "defaultMode": "standard" },
  "privacy": { "exclude": ["private/**"] },
  "verification": {
    "commands": [{ "command": "cargo", "args": ["test"] }]
  }
}

MCP, API and custom agents

MCP: threadport mcp serves the context, the saved handoff and session tools over stdio. threadport mcp setup prints the commands for Claude Code and Codex.

claude mcp add --scope project threadport -- threadport mcp

HTTP API: threadport serve --port 0 listens on 127.0.0.1 and prints a temporary Bearer token.

Custom agents: describe any CLI agent in a JSON manifest. It runs only after you trust it.

{
  "version": 1,
  "id": "my-agent",
  "label": "My Agent",
  "command": "my-agent",
  "args": ["Read {contextFile} and continue the current task."],
  "capabilities": ["filesystem_access", "git_access"]
}

threadport plugin add ./agent.json
threadport plugin trust my-agent

VS Code extension

Available on the Visual Studio Marketplace. It opens sessions as editable Markdown documents, shows tasks with checkboxes, runs the next instruction with Ctrl + Enter, and offers an @threadport chat participant and an MCP server to VS Code agents. It uses the same .threadport/ data as the CLI.

code --install-extension aristideghost.threadport-vscode

Troubleshooting

"Project is not initialized": Run threadport init at the project root. Commands then work from any subdirectory.
An agent is not found: Run threadport doctor. The agent CLI must be on your PATH.
A project agent is refused: Review its manifest, then run threadport plugin trust <id>.
Verification says "stale": A file changed after the checks ran. Run threadport verify again.

Edit this page on GitHub

Documentation

ThreadPort enregistre ce qui se passe pendant une tâche de développement et le transmet à l’agent IA suivant sous la forme d’un pack de contexte court et sourcé. Cette page couvre la CLI (version 0.5 et suivantes). Elle présente aussi l’extension VS Code.

Installation

Il faut Node.js 24 ou plus récent et npm. Git est recommandé : sans lui, ThreadPort fonctionne, mais ne peut ni prendre d’instantanés ni rattacher une vérification à un commit.

npm install -g threadport
threadport --version
threadport doctor

doctor affiche votre version de Node, indique si le projet est initialisé et quels agents (Claude Code, Codex) sont installés.

Démarrage rapide

Lancez ces commandes à la racine du projet à suivre.

threadport init
threadport new "Fix token rotation"
threadport task add "Write a concurrency test"
threadport decision "Keep token IDs in Redis" -r "Shared revocation"
threadport run claude

Quand Claude se termine, enregistrez ce que son interface n’a pas exposé, puis passez la main :

threadport note "The collision happens during simultaneous renewal"
threadport check npm test
threadport switch codex

Codex démarre avec l’objectif, la tâche ouverte, la décision et le test en échec. Les commandes fonctionnent depuis n’importe quel sous-dossier du projet.

Fonctionnement

Session: Une tâche avec un objectif. Une seule session est active à la fois ; open et resume permettent d’en changer.
Enregistrements: Tâches, notes, erreurs, décisions, résultats de tests, contraintes, fichiers pertinents et mémoire du projet. Chacun a un identifiant, modifiable ou supprimable.
Pack de contexte: Du Markdown construit à partir de la session et de l’état Git en direct, trié par priorité et limité à un budget de tokens. Chaque section indique sa source.
Exécutions: Chaque lancement d’agent est enregistré avec son statut et son code de sortie. Une exécution arrêtée brutalement est marquée interrupted.

Tout est stocké dans .threadport/threadport.sqlite, dans votre projet. ThreadPort écrit .threadport/.gitignore pour que Git l’ignore.

Commandes

Commande	Rôle
`init`	Initialise le projet dans le dossier courant.
`new "objectif"`, `sessions`, `open <id>`, `resume <id>`	Crée, liste et réactive des sessions. `resume` affiche aussi le contexte.
`rename`, `finish`, `delete`	Renomme, termine ou supprime définitivement une session.
`status`, `timeline`, `snapshot`	Affiche la session active, ses événements, ou capture l’état Git.
`task add`, `task done <id>`, `task list`	Suit les tâches.
`decision "titre" -r "raison"`, `decisions`	Enregistre et liste les décisions.
`note`, `error`, `constraint`, `memory`	Enregistre des notes, des problèmes, des contraintes et des connaissances partagées par toutes les sessions.
`file <chemin>`, `files`, `artifact <chemin>`	Marque des fichiers et artefacts pertinents ; `files` liste aussi les changements Git.
`record edit`, `record delete`	Corrige ou supprime un enregistrement.
`check <cmd> [args]`, `test-result`, `command-log`	Lance une commande et enregistre son résultat, ou consigne une commande lancée ailleurs.
`summary`, `search "termes"`	Résume la session, ou recherche localement dans toutes les sessions.
`context [--mode] [--explain]`	Affiche le pack de contexte et son budget de tokens.
`run`, `switch`, `continue <agent>`	Lance un agent avec le contexte, ou reprend sa session native.
`verify`, `handoff`, `link`	Vérifie le travail, relit un handoff, lie une issue ou une pull request GitHub.
`export`, `import`	Transfère une session vers une autre copie du projet.
`fork`, `compare`	Essaie plusieurs agents dans des worktrees Git séparés et les compare.
`agents`, `doctor`, `config`	Liste les agents, vérifie l’environnement, modifie les réglages.
`hook`, `plugin`, `privacy`	Hooks de cycle de vie, agents personnalisés, audit et nettoyage de confidentialité.
`tui`, `serve`, `mcp`	Menu en terminal, API HTTP locale, serveur MCP.

Lancez threadport <commande> --help pour voir toutes les options.

Modes de contexte

Mode	Budget	Contenu
`minimal`	500 tokens	Objectif, éléments prioritaires et quelques événements.
`standard`	1 500 tokens	Résumé, mémoire, contraintes, tâches, erreurs, décisions, tests, notes, fichiers et état Git selon la place.
`deep`	4 000 tokens	La même chose, avec plus d’événements et un diff Git filtré.
`full`	10 000 tokens	La même sélection avec un budget plus large.

threadport context --mode deep --explain
threadport config set-default-mode deep

Les tokens sont comptés avec cl100k_base comme référence et peuvent différer du tokenizer d’un modèle donné. --explain liste les sources utilisées et les sections qui n’ont pas tenu.

Lancer des agents

run lance Claude Code ou Codex dans votre terminal avec le fichier de contexte. switch fait de même et enregistre le passage de relais depuis l’agent précédent.

threadport run codex --structured
threadport status
threadport continue codex

--structured lance l’agent sans son interface interactive et enregistre les commandes, messages, erreurs et l’identifiant de session de son flux JSON. continue reprend ensuite cette session native.

Passages de relais automatiques

threadport hook install claude
threadport hook install codex

Ces hooks locaux au projet donnent le contexte à l’agent au démarrage, enregistrent les fichiers qu’il modifie et écrivent un résumé à la fin. Ils ne copient jamais les conversations, les arguments ni la sortie des outils. Codex vous demande d’approuver les nouveaux hooks avec /hooks.

Vérifier et passer la main

verify lance les scripts check, test et build d’un projet Node, ou les commandes de .threadport/config.json, et rattache le résultat à l’état Git actuel. Toute modification de fichier rend le rapport obsolète.

threadport link issue https://github.com/owner/repo/issues/42
threadport verify
threadport handoff draft --out .threadport/handoff.md
threadport handoff save .threadport/handoff.md
threadport handoff show

Confidentialité

Les clés d’API, tokens GitHub, GitLab, npm, Stripe, AWS, Google et Slack, JWT, en-têtes Bearer, identifiants dans les URL, clés privées et valeurs token= ou password: sont masqués avant l’enregistrement et avant tout passage de relais. La détection est heuristique.
.env, .env.*, *.pem, *.key, credentials.json et secrets/** sont exclus par défaut. Ajoutez vos motifs, un par ligne, dans .threadportignore.
Les instantanés stockent les chemins, pas le contenu des diffs. Un diff n’apparaît qu’en contexte deep et full.

threadport privacy audit --show-context
threadport privacy scrub

scrub applique les règles actuelles aux données enregistrées avant elles.

Configuration

Les réglages du projet sont dans .threadport/config.json :

{
  "context": { "defaultMode": "standard" },
  "privacy": { "exclude": ["private/**"] },
  "verification": {
    "commands": [{ "command": "cargo", "args": ["test"] }]
  }
}

MCP, API et agents personnalisés

MCP : threadport mcp sert le contexte, le handoff enregistré et les outils de session via stdio. threadport mcp setup affiche les commandes pour Claude Code et Codex.

claude mcp add --scope project threadport -- threadport mcp

API HTTP : threadport serve --port 0 écoute sur 127.0.0.1 et affiche un token Bearer temporaire.

Agents personnalisés : décrivez n’importe quel agent en CLI dans un manifeste JSON. Il ne s’exécute qu’après votre approbation.

{
  "version": 1,
  "id": "my-agent",
  "label": "My Agent",
  "command": "my-agent",
  "args": ["Read {contextFile} and continue the current task."],
  "capabilities": ["filesystem_access", "git_access"]
}

threadport plugin add ./agent.json
threadport plugin trust my-agent

Extension VS Code

Disponible sur le Visual Studio Marketplace. Elle ouvre les sessions comme des documents Markdown modifiables, affiche les tâches avec des cases à cocher, lance la prochaine instruction avec Ctrl + Entrée, et propose un participant de chat @threadport et un serveur MCP aux agents de VS Code. Elle utilise les mêmes données .threadport/ que la CLI.

code --install-extension aristideghost.threadport-vscode

Dépannage

« Project is not initialized »: Lancez threadport init à la racine du projet. Les commandes fonctionnent ensuite depuis n’importe quel sous-dossier.
Un agent est introuvable: Lancez threadport doctor. La CLI de l’agent doit être dans votre PATH.
Un agent du projet est refusé: Relisez son manifeste, puis lancez threadport plugin trust <id>.
La vérification est « stale »: Un fichier a changé après les vérifications. Relancez threadport verify.

Modifier cette page sur GitHub