tackroom

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 2, 2026 License: MIT Imports: 1 Imported by: 0

README

tackroom

Dotfiles for your AI agents.

Release brew npm CI License

brew install yourconscience/tap/tackroom

Formerly dotagents. Renamed in v1.0 because several unrelated tools, including Sentry's @sentry/dotagents, ship a dotagents binary that manages the same ~/.agents directory.

Overview & comparison → · Releases · Docs

Why

If you use more than one coding agent, you maintain the same skills, MCP servers, hooks, and roles in a different place and format for each one. Copying them by hand drifts within a week. Skills have converged on one open convention (agentskills.io), plugins on agent-plugins-spec, and root instructions on AGENTS.md — but every harness still stores and renders config in its own native format. tackroom applies the dotfiles pattern to that last mile: one versioned repo, rendered natively per harness, with memory tooling built in.

Quick start

brew install yourconscience/tap/tackroom   # or: npm i -g tackroom
# no brew/npm? curl -fsSL https://raw.githubusercontent.com/yourconscience/tackroom/main/scripts/install.sh | sh
tackroom setup                             # detect harnesses, import, first sync

setup creates ~/.agents, detects installed harnesses, imports existing content by copy after a per-item review, and runs the first sync. To carry the setup to other machines, add a private git remote and repeat — details in docs/setup.md.

tackroom status   # per-harness sync state
tackroom doctor   # health checks: frontmatter, lock pins, audits, hooks

Upgrading from dotagents

tackroom 1.0 is the dotagents CLI under a new name. An existing config root needs its files renamed once; tackroom refuses to run until they are.

dotagents cron --remove                        # only if you installed the cron entry
cd ~/.agents
git mv dotagents.yaml tackroom.yaml
git mv dotagents.lock tackroom.lock
git mv .dotagents-starter.json .tackroom-starter.json
mv dotagents.local.yaml tackroom.local.yaml    # only if you have one

Then:

  • In .gitignore, replace dotagents.local.yaml with tackroom.local.yaml so machine-local overrides stay out of git.
  • Move skills/dotagents to skills/tackroom. If you never edited it, copy this repo's skills/tackroom over it; otherwise replace dotagents with tackroom inside it.
  • Install tackroom, run tackroom sync, then tackroom cron if you use it, and remove the old dotagents binary.

Role files that dotagents rendered into harness folders are adopted and rewritten on the first sync.

What it syncs

Five surfaces, each rendered into the harness's own format — tackroom does not invent compatibility files a harness cannot consume:

Harness Skills Roles MCP Hooks Plugins
Amp yes, config-driven --⁑ yes --⁑ --
Claude Code yes yes yes yes --
Codex yes yes yes yes planned
Factory Droid yes yes yes yes --
Hermes yes -- yes yes --
OpenCode yes† yes yes -- --
Qwen Code yes, config-driven yes yes yes skills + MCP§
OMP (pi fork) yes yes yes --‡ --
Pi* yes yes* yes* -- skills + MCP*

* Vanilla pi gains managed roles through pi-subagents and managed MCP/Agent Plugin projection through pi-mcp-adapter. A Pi target can also declare a pinned packages list; sync writes that list to ~/.pi/agent/settings.json, and Pi installs missing packages on its next startup. Tackroom does not install the Pi executable itself. The OMP fork remains a separate target.

agents:
  - name: pi
    enabled: true
    detect: pi
    skill_root: ~/.pi/agent/skills
    agent_root: ~/.pi/agent/agents
    packages:
      - npm:pi-mcp-adapter@2.33.0
      - npm:pi-subagents@0.67.0

† OpenCode reads ~/.agents/skills/ natively; its only hook surface is a JS plugin API. ‡ OMP has no managed hook surface yet; register memory hooks manually if needed. § Qwen Code natively loads Agent Plugins v1 skills and MCP servers; tackroom manages those same surfaces without rewriting the plugin. ⁑ Amp's hook and role surfaces use plugin-based models incompatible with tackroom' script-based hooks and per-agent role files.

OpenClaw is not currently supported. Native skill discovery from ~/.agents/skills may work due to OpenClaw's multi-tier skill precedence, but this is unverified and unmanaged. A managed harness entry is planned for a future release. A "yes" above only appears after end-to-end verification.

Skills

A skill is a directory under ~/.agents/skills/ with a SKILL.md (agentskills.io convention) — create once, appears everywhere. External skills are treated like dependencies: pinned in tackroom.lock, materialized for diffing, audited by tackroom doctor. Details in docs/skills.md.

Memory

Pick a tier during setup: off, basic (session digests), or memsearch (indexed search). On top of that, sync builds two Go helpers into ~/.local/bin: knowledge-sync (vault git sync) and rem:

rem add -src claude "prefers pnpm for Node work"   # capture a candidate fact anywhere
rem dream                                          # consolidate candidates into review reports
rem dream --apply                                  # collapse exact-duplicate records (backup + commit)
rem search "quota preferences"                     # semantic search over captured memory

Candidates are inert until you promote them into durable instructions — consolidation is report-first by design, because automatically rewriting memory is how agents quietly corrupt their own instructions. sync keeps the managed memory code layer current and removes files a release no longer ships; anything you edited yourself is reported and left alone. Design notes in docs/memory.md.

Roles

Markdown role definitions in ~/.agents/agents/, rendered to each harness's native format (Claude Markdown, Codex TOML, Qwen Markdown, Droid). Generic model tiers (haiku/sonnet/opus) render natively for Claude and Droid; Codex omits them and uses its own default unless a per-harness override pins an exact id. Six starter roles ship with the tool; yours win on name collision. Details in docs/roles.md.

Commands

tackroom setup    [--memory off|basic|memsearch] [--yes] [--dry-run] [--json]
tackroom status   [--verbose] [--agents ...]
tackroom sync     [--pull] [--agents ...]
tackroom doctor   [--e2e] [--agents ...]
tackroom config   validate|print
tackroom view     [--addr 127.0.0.1:8765] [--no-open] [--secure-cookie] [--ssh-host user@host]  # loopback web config UI
tackroom skill    new|list|info|update|promote
tackroom publish  [--target NAME] [--skills a,b] [--dry-run] [--json] [--yes]  # push skills to a remote registry
tackroom mcp      list|add|import|remove
tackroom hook     list [query] | remove [--dry-run] <query>

Companion tools

tackroom does one job. These tools pair well with it; install and run them on their own:

Tool Purpose Run
HarnessKit Inspect and audit skills, MCP servers, hooks, and native harness configuration hk serve
AgentsView Search and replay sessions; inspect tool telemetry, token usage, and estimated cost agentsview serve

Treat HarnessKit as read-mostly: its enable, disable and deploy actions bypass tackroom, so reconcile any changes with tackroom sync.

tackroom skill list remains the built-in provenance view for each harness skill root. It reports managed links, foreign symlinks, unmanaged directories, drift, broken links, and estimated context cost.

tackroom hook list [query] inventories native hook registrations and marks canonical entries as managed and missing script targets as stale. To clean up a hook installed outside tackroom, preview with tackroom hook remove --dry-run <query>, then rerun without --dry-run; unrelated hook entries are preserved. tackroom doctor reports stale native hooks, and tackroom sync reconciles the remaining canonical hooks afterward.

Installing skills without tackroom

A tackroom-format repo also works as a plain skills source. Anyone can copy individual skills into their harness of choice with the skills.sh installer, no tackroom install needed:

npx skills add yourconscience/myagents -s tackroom --copy   # verified: copies cleanly, no symlinks

That path copies editable files (the "fork" model); tackroom users get the symlink-to-canonical model with lock-pinned updates. Pick one per machine — installing both leaves you with every skill twice.

Configuration

~/.agents/tackroom.yaml is the single source of truth; setup fills in detected harnesses. Resolution order: --config <path> → $TACKROOM_HOME/tackroom.yaml → ~/.agents/tackroom.yaml; never walks the current project. Machine-local entries overlay via tackroom.local.yaml. Managed entries are marked in native configs; anything else is left untouched.

Canonical config authoring

tackroom view (browser web UI) edits the resolved canonical YAML through a review-first flow. Shared and tackroom.local.yaml are separate editable layers; the effective view is read-only. Structured edits preserve comments and unknown fields, and a save never runs sync implicitly. tackroom config validates or prints the result.

tackroom view --no-open --addr 127.0.0.1:8765   # loopback web UI, print the URL
tackroom config validate
tackroom config print

The view web server is loopback-only, session-cookie authenticated (a one-time startup token swapped for an HttpOnly, SameSite=Strict cookie), CSRF- and origin-checked on mutations, guards saves by revision, and keeps sync as a separate preview/confirm step. It prints the tokenized URL on its own line and opens your default browser locally; --no-open skips that, and --ssh-host user@host (or an SSH session, via SSH_CONNECTION) prints an ssh -L tunnel command for reaching the loopback UI from another machine. For deliberate HTTPS tailnet access, expose the loopback listener yourself:

tackroom view --no-open --secure-cookie --addr 127.0.0.1:8765
tailscale serve --bg --set-path /tackroom http://127.0.0.1:8765

Releases

Releases are cut from main after the release PR is reviewed and merged, and only with explicit approval:

scripts/release.sh vX.Y.Z    # verify + tag; CI publishes binaries, brew tap, npm

The script refuses to run unless the tree is clean, HEAD matches origin/main, the tag is strict vMAJOR.MINOR.PATCH, and every check passes. Pushing the tag starts .github/workflows/release.yml, which re-verifies the tag against main and a green ci.yml run, waits on the protected release environment, then publishes binaries, the Homebrew tap, and the npm wrapper.

Documentation

Project-level generators (rulesync, ruler) win on tool breadth; tackroom is user-level — one private repo, nine targets deep, pinned externals, review-first memory. Full table in docs/comparison.md.

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source
var StarterAssets embed.FS

StarterAssets contains the public files that tackroom setup scaffolds into a user-owned canonical configuration root. The CLI must not read these paths from the source checkout at runtime; release binaries carry them here.

This file lives at the repository root on purpose: go:embed can only reach files at or below its own directory, so the manifest cannot move into internal/. Keep the embed list in sync with the public starter inventory.

Functions

This section is empty.

Types

This section is empty.

Directories

Path Synopsis
cmd
tackroom command
internal
agentrole
Package agentrole parses canonical tackroom roles and projects them into harness-native role formats.
Package agentrole parses canonical tackroom roles and projects them into harness-native role formats.
app
memory
tools/rem command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL