tacticyl
v0.1.16
Published
The companion runs as a small program beside your code, gives Claude Code, Codex and Cursor the tools of your Tacticyl business map, keeps your map current from each commit, and reads the repository in place to report facts to your Tacticyl cloud workspac
Readme
tacticyl
This is the companion for your Tacticyl business map and runs as a small program beside your code. It serves your map to Claude Code and Cursor, keeps your map current from each commit, and checks the folders your artifacts live in. It reads the repository in place, and only reports facts to your Tacticyl cloud workspace.
Install
npm i -g tacticyl
tacticyl --versionOne line on a machine with Node 22 or later (node --version prints the one it has).
Update
npm i -g tacticyl
tacticyl --versionYou can update the companion with the same command you used to install it, and tacticyl --version
will print the installed version. When a newer version is available, a tacticyl command will
print one line saying so and still run; if the installed version is older than the oldest one
Tacticyl accepts, the command will not run until you update. Links, sign-in and hooks in your
repositories stay as they are after you update. An agent session in Claude Code, Codex or Cursor
that is already open will keep using the old version until you restart it.
What it does on your machine
- Installed. Running
npm i -g tacticylwill add a launcher, one bundled program file and atacticylcommand. The companion runs in the background while an agent session is connected and for a few minutes after the last one ends. It does not start at boot and does not update itself. When you install or update the package with npm, a step that runs after the install will stop any companion running on this machine, and the version you installed will take its place. Agent sessions that were connected will reconnect to the new version the next time they use a tool. This step only contacts the companion on this machine (127.0.0.1) and prints nothing. If you install with--ignore-scripts, this step will not run, and the old companion will keep running until it stops on its own a few minutes after the last session ends. - When it runs. One companion runs per machine. It starts in the background when Claude Code, Codex or Cursor starts
tacticyl servefor a session, serves every repository an agent is working in, and stops a few minutes after the last agent session ends. You can runtacticyl companion --stayto keep the companion running until you stop it. The companion also runs when you run atacticylcommand, and from hooks in a linked repository after eachgit commit, at the start of Claude Code or Cursor sessions, and after those agents edit files. Its status page is served at a 127.0.0.1 address that only this machine can reach. - What it reads. The companion reads the linked repository's manifests, lockfiles, migrations, compose and deploy files, environment variable names,
.tacticyl/inbox.md, the opening of its README and architecture documents, and its commit and remote. In folders mounted withtacticyl link --store, it reads only the files the map names and the folders you chose to watch, to compute a hash of each. - What it reports. The companion reports facts to your Tacticyl cloud workspace at
https://app.tacticyl.com. It reports facts about the repository: names, versions, counts, the remote and commit, environment variable names, the opening of the README and architecture documents, and the lines your agents append to.tacticyl/inbox.md. For each file in a store folder it reports the name, hash, size and time. It also reports the machine's name and what your agents send through Tacticyl's tools: a proposal, a document's path and summary, a finding's text, or an answer. Secrets are reported by name. When a command or a background run fails, the companion keeps a short note of the error on this machine, in~/.tacticyl/errors.json, and sends it to your workspace when you runtacticyl reportand confirm it, or while error reports are on withtacticyl report on. A report contains the error and where in the companion it happened, and the companion, operating system and Node.js versions; file contents and environment variables are not included. - What it writes. In the repository, the companion writes
TACTICYL.md, the.tacticyl/folder, and entries inCLAUDE.md,AGENTS.md,.mcp.json,.cursor/,.claude/settings.jsonand.git/hooks/post-commit. On this machine, it stores your sign-in in the keychain or~/.tacticyl/credentials.jsonand adds a tool entry to~/.codex/config.toml. - Removing it. Running
tacticyl removein the repository will remove what the companion set up there and sign this machine out, andnpm uninstall -g tacticylwill remove the program. You can runtacticyl remove --dry-runto list the changes first.
Sign in
tacticyl loginRunning tacticyl login will open a browser, where you approve this machine by name. The sign-in
is stored in your operating system's keychain. Your Tacticyl cloud workspace also shows a one-line
command, tacticyl login --token <code>, on the Overview, Agent and Account pages that pairs this
machine. Running that line inside a repository will also link the repository, write the agent
files and install the hooks.
In a repository
tacticyl link --business <id> # once per repository; the id is in your workspace's URL
tacticyl project # writes TACTICYL.md and gives your agents the tools
tacticyl serve # connects Claude Code, Codex and Cursor to the companion over stdio
tacticyl audit # reads the code and keeps the map true
tacticyl hooks install # a commit runs the audit from now on
tacticyl status # what it is doing, and the fix for anything wrongRunning tacticyl link will match an existing root by the repository's remote. A business your
workspace drafted from this repository will be joined.
project writes TACTICYL.md and, beside it, the files each agent reads: a block in CLAUDE.md
for Claude Code, .cursor/rules/tacticyl.mdc and a Claude Code skill, and a block in AGENTS.md
for agents that follow that convention. Each block says when to use Tacticyl, so your agents ask
the map before they search the code; beneath it, "Your notes on Tacticyl" is yours and is never
touched. If this repository already has its own CLAUDE.md or AGENTS.md, you are asked once
whether Tacticyl may keep its block in them, and once whether to commit the files it writes;
--prompts own, --prompts leave, --git commit and --git ignore change either answer later,
and leave takes the block out again. It also gives Claude Code, Codex and Cursor Tacticyl's
tools. If an agent's program is installed, project uses that agent's own command
(claude mcp add or codex mcp add); otherwise it writes the agent's config file (.mcp.json for
Claude Code, an entry in ~/.codex/config.toml for Codex). Cursor has no such command and will
always get .cursor/mcp.json. Codex's setting applies to every repository on this machine. You can
skip an agent with --no-claude-code, --no-codex or --no-cursor.
tacticyl --help lists the rest.
Help
You can open Help in the top bar of your Tacticyl cloud workspace to walk through each step on a worked example. This machine appears on the Account page in your workspace once it has signed in.
