Installation

Choose an installation methodCopy Anchor Link

Python 3 is required to run DevThread's local scripts with any installation method. The recorded Python tests used 3.13. For the DevThread npm installer, check node --version and npm --version. On Windows, check python --version; on Linux or macOS, use python3 --version.

DevThread v0.1.0 is available on npm under the MIT license, with no runtime npm dependencies. The npm installer is the simplest starting point. The source is also available in the GitHub repository.

Install with the DevThread npm packageCopy Anchor Link

The installer uses Node's built-in modules and native paths for Windows, Linux, and macOS. It copies the complete skill and refuses to replace an existing file, directory, or linked destination. Installation does not initialize or change the project's development map.

Run this in your existing project using PowerShell, bash, or zsh:

npx devthread install

This installs to .agents/skills/devthread/ in the current project. These options use the same command on all three OSes:

# Available across projects: ~/.agents/skills/devthread/
npx devthread install --global

# An existing project, including a path with spaces
npx devthread install --project "PATH_TO_PROJECT"

# This exact skill directory
npx devthread install --dest "PATH_TO_SKILL_DIRECTORY"

# Preview the destination without creating files
npx devthread install --global --dry-run

Windows user paths resolve under the user's home directory, such as C:/Users/NAME/.agents/skills/devthread/. Linux and macOS use their respective home directories. The skill files do not require administrator access or symlinks. To select the initial release explicitly, use npx devthread@0.1.0 install with the same options.

Install from sourceCopy Anchor Link

Get the source, then use the existing target project's path:

git clone https://github.com/kurarensu16/devthread.git
cd devthread
node bin/devthread.mjs install --project "PATH_TO_PROJECT" --dry-run
node bin/devthread.mjs install --project "PATH_TO_PROJECT"

Install a locally built archiveCopy Anchor Link

From the checkout, create the package and install its command:

npm pack --ignore-scripts
npm install --global ./devthread-0.1.0.tgz
devthread install --global --dry-run
devthread install --global

The first global command installs the npm CLI; devthread install --global installs the skill files. Neither action updates an existing skill automatically. If the destination exists, inspect and preserve that installation before selecting a new destination or performing a reviewed update.

OS verificationCopy Anchor Link

The recorded CI run exercised the actual npm archive, preservation checks, and bundled scripts on all three OSes. It also passed the website checks. Live registry installation was additionally verified on Windows with Node 22.18.0 and Python 3.13. Linux and macOS registry downloads have not been separately exercised; their archive and script checks pass in CI. Other Python versions remain untested.

DevThread has been discovered and loaded in Codex on Windows from ~/.agents/skills/devthread/; all 19 installed skill files match the source. Independent review of a separate fresh-chat workflow under the new name remains pending. Agent discovery on Linux and macOS has not been tested. See compatibility for the full evidence limits.

Install through CodexCopy Anchor Link

OpenAI's skill guidance describes using the built-in installer to download skills from other repositories. Send this prompt in Codex:

$skill-installer Install the devthread skill from kurarensu16/devthread, branch master, path skill/devthread. Preserve any existing installation.

Check the destination reported by the installer. Then use the verification steps below. This route has not yet been exercised with DevThread.

Install with the skills CLICopy Anchor Link

The Vercel Labs skills CLI supports GitHub sources and a Codex target. Run this from the project where you want to use DevThread:

npx skills add kurarensu16/devthread --skill devthread --agent codex --copy

The default is a project installation at .agents/skills/devthread/. --copy installs the complete files without requiring symlinks. To make the skill available across projects, add --global; the CLI uses ~/.agents/skills/devthread/ for that scope. Review the installer's destination and confirmation before proceeding.

To use this installer with the current local source, run from the DevThread checkout:

npx skills add ./skill/devthread --skill devthread --agent codex --copy

These CLI commands follow the installer's documented options; they have not been executed for DevThread here. File installation and fresh-chat discovery still need verification. Other agent targets remain untested.

What about npm install devthread?Copy Anchor Link

npm install devthread downloads the published package as a dependency; then npx devthread install places the skill in its discovery directory. The single npx devthread install route downloads and runs the CLI without adding DevThread to your project's dependencies.

For a persistent CLI command, install it globally, then install the skill into your current project:

npm install --global devthread
devthread install

Add --global to the second command when the skill should be available across projects. Global npm CLI installation uses your configured npm prefix and may require its usual permissions; the skill files go into your project or user directory.

Manual installation on WindowsCopy Anchor Link

Have a local DevThread source checkout, Codex with local repository access, and Python 3. The recorded tests used Windows and Python 3.13. Run python --version to check your Python installation.

Copy the full skill/devthread/ directory into ~/.agents/skills/devthread/. Keep its references/, templates/, scripts/, and LICENSE together with SKILL.md. This is the user location in current OpenAI guidance, and the renamed skill has been discovered and loaded there in Codex on Windows. The manual copy command below has not been separately exercised; the npm installer provides the tested copying behavior.

From the DevThread checkout root in PowerShell, use the following command. It stops if an installation already exists so that an existing skill is not overwritten.

$devthreadSkill = Join-Path $env:USERPROFILE '.agents\skills\devthread'
if (Test-Path -LiteralPath $devthreadSkill) {
  throw 'DevThread is already installed. Review the existing copy before updating it.'
} else {
  New-Item -ItemType Directory -Path (Split-Path $devthreadSkill) -Force | Out-Null
  Copy-Item -LiteralPath '.\skill\devthread' -Destination $devthreadSkill -Recurse
}

Check the files and scriptsCopy Anchor Link

For the manual Windows installation, continue in the same PowerShell session. For another method, set $devthreadSkill to the installation directory reported by that installer first:

Test-Path (Join-Path $devthreadSkill 'SKILL.md')
Test-Path (Join-Path $devthreadSkill 'references\planning.md')
Test-Path (Join-Path $devthreadSkill 'templates\TASK.md')
python (Join-Path $devthreadSkill 'scripts\init.py') --help
python (Join-Path $devthreadSkill 'scripts\validate.py') --help
python (Join-Path $devthreadSkill 'scripts\status.py') --help

The three path checks should return True, and each script should print usage information.

For a project installation on Linux or macOS, run these from the target project:

test -f .agents/skills/devthread/SKILL.md
python3 .agents/skills/devthread/scripts/init.py --help
python3 .agents/skills/devthread/scripts/validate.py --help
python3 .agents/skills/devthread/scripts/status.py --help

For global or custom installation, use the corresponding installed path. CI exercises Python init, validation, and status after installing the npm archive on Linux and macOS; the manual shell checks above have not been run separately.

Invoke the skillCopy Anchor Link

Start a fresh Codex chat with your project open and explicitly request:

Use $devthread to understand this repository. Report observed facts, inferences, and the next useful action.

Confirm the agent loaded DevThread before relying on its workflows. The renamed skill has been loaded in the current Codex chat on Windows. Independent review of a separate fresh-chat workflow remains pending; the older fresh-chat recovery evidence used DevMap. Codex detects skill changes automatically; if the skill is missing, restart Codex and consult the troubleshooting guide.

Existing project mapsCopy Anchor Link

The renamed scripts accept legacy .devmap/ state in place. New projects use .devthread/. Keep only one active map per project; when both directories exist, the scripts stop for review rather than merging or choosing one.

Updates and other agentsCopy Anchor Link

Review changes before replacing an installed copy, and retain local modifications. The website does not provide an automatic updater. Other hosts and installation paths are untested; follow their current packaging guidance and record installation and workflow evidence before advertising support.