Introduction
Install DevThread, ask your coding agent to inspect a project, and keep its plan beside the code.
DevThread is an open-source Agent Skill: instructions and local helpers your coding agent uses to understand a repository, plan work, compare the plan with code, and explain the next action.
It uses the host coding agent's model, tools, and repository access. Context persists in a project map—Markdown and JSON files containing repository findings, requirements, tasks, dependencies, decisions, and check results.
How it works
You ask the agent to inspect the repository, save a map, reconcile it with code and check results, or resume from the saved files. Each workflow runs when requested. When the plan and implementation disagree, the agent records the gap or conflict and recommends a justified action.
Installation copies the skill into .agents/skills/devthread/. Initialization and planning create or update .devthread/. Understanding and status leave application code unchanged; source edits require an implementation request.
Quick start
What you need
| Action | Requirement |
|---|---|
| Install with npm | Node.js 22+ and npm; manual copying does not need Node |
| Use the skill | A coding agent that can discover skills and read your repository; Codex discovery is observed on Windows |
| Run the local helpers | Python 3, using only its standard library; Python 3.13 is the tested version |
The tested versions and operating systems are recorded in compatibility. Contributor tooling is described separately in development setup.
Install in your project
From an existing project directory, run:
npx devthread installThe complete skill is installed at .agents/skills/devthread/. Existing destinations are preserved. Add --global for availability across projects, or --dry-run to preview without writing files. Installation covers all options and source/archive alternatives.
Ask your agent to inspect the repository
Open a fresh Codex chat in that project and ask:
Use $devthread to understand this repository.
Read its existing instructions, source, and tests.
Separate observed facts, inferences, and unknowns.Review the findings. To create a map, give the agent a bounded goal:
Use $devthread to initialize a development map for this repository.
Plan the work for this goal: [describe your goal].
Preserve existing files and instructions.Review the map before implementation. Continue with the existing repository or new repository walkthrough.
What DevThread creates
Initialization creates the map's core files and empty task/report directories. Planning adds tasks; verification adds reports. This is the structure of the recorded Taskboard example after planning and verification:
.devthread/
├── config.json
├── PROJECT.md
├── REQUIREMENTS.md
├── ARCHITECTURE.md
├── ROADMAP.md
├── DECISIONS.md
├── tasks/
│ ├── TASK-001.md
│ └── TASK-002.md
└── reports/
└── TASK-002-verification.mdProject and architecture files save context and findings. Requirements and the roadmap link goals to work. Tasks contain scope, dependencies, acceptance criteria, status, and evidence. Reports record exact commands and passed, failed, or not-run outcomes. config.json declares the format version. See project state and the file format for details.
In a new chat, the agent reads these files to recover context. Reconciliation checks that saved context still matches the repository.
Evidence and review
Source inspection supports understanding; it does not prove runtime behavior. DevThread preserves earlier failures and checks that could not run.
Evidence and task status describe different things. A task can have verified checks while remaining in review. Review the agent's acceptance checks and decide whether the task is accepted; the agent records that decision. Changes and passing tests do not automatically mark a task done.
Scope and compatibility
DevThread includes the skill, templates, local Python helpers, landing page, and documentation. It needs no DevThread service or model API. Your coding agent supplies its configured model and access.
Installer and Python checks pass on Windows, Linux, and macOS with Node 22/24 and Python 3.13. Live registry installation and renamed skill discovery are observed on Windows. Independent review of a separate fresh-chat workflow remains pending; other agents and Python versions remain untested. Read compatibility and safety and privacy for the full scope and evidence limits.