Skip to main content

The tk CLI

tk (short for terminal-kit) is a small command-line helper that scaffolds a shared, file-based communication workspace for orchestrating multiple AI agents across separate TermFlow terminals. Its one useful job is tk init.

What tk is (and isn't)

tk is a developer utility that ships in the TermFlow source tree under terminal-kit/, not part of the installed desktop app. It writes files into your project. It does not run agents, start the API, or bundle any AI — TermFlow always uses the agent and API keys you bring yourself.

An honest note: The MCP configuration tk init generates is stale and will not connect. It emits a stdio server with a placeholder path (path/to/auto-terminal/mcp-server/build/index.js), uses the wrong server key (open-terminal), and lists only 5 tools. TermFlow's MCP server is a streamable-HTTP server on port 42032, keyed auto-terminal. Use tk init only for the .agent-comms/ scaffolding, and configure MCP through the in-app Connect modal instead — see Connect an agent.

What tk init does​

Run it from the root of the project you want to set up:

cd /path/to/your/project
tk init

It creates the following, aborting (exit code 1) if any of the targets already exist unless you pass --force:

your-project/
├── .agent-comms/                     # cross-terminal communication workspace
│   ├── requests/                     # PM -> Leader Agent requests
│   ├── responses/                    # Leader Agent -> PM responses
│   ├── status/                       # real-time status files
│   ├── shared/
│   │   └── findings/                 # research results cache
│   └── README.md                     # quick-reference for the protocol
├── .mcp.json                         # MCP config (STALE — do not use, see note above)
├── .gemini/
│   └── settings.json                 # Gemini MCP config (STALE — do not use)
├── .claude/
│   └── settings.local.json           # Claude Code permission allow-list
└── docs/
    └── multi-team-agent-workflow.md  # protocol documentation (omit with --no-docs)

Of these, the genuinely useful output is the .agent-comms/ tree and, optionally, the workflow doc. The three MCP/agent config files carry the stale settings described above and should be replaced with configuration generated by the Connect modal.

Flags​

FlagDefaultEffect
-f, --forceoffOverwrite existing files/folders instead of aborting when they already exist.
--no-docsdocs includedSkip generating docs/multi-team-agent-workflow.md.
--api-url <url>http://localhost:42031The API URL baked into the generated MCP config's env. (The default matches TermFlow's production API port, 42031.)
note

Because the generated MCP config is stale regardless of --api-url, this flag mainly documents intent. It does not make the generated .mcp.json usable. Configure MCP in-app instead.

The .agent-comms protocol​

.agent-comms/ is a plain-filesystem message bus. There is no daemon and no database — agents in different terminals coordinate by writing and reading Markdown files in a shared directory. This keeps the protocol transparent, greppable, and easy to debug.

PathRoleFile naming
requests/Project Manager to Leader Agent requestsREQ-YYYYMMDD-NNN.md
responses/Leader Agent to Project Manager responsesRESP-YYYYMMDD-NNN.md
status/Real-time per-terminal statusterminal-{id}.status
shared/Shared context and cached findings(free-form)
shared/findings/Cache of research results(free-form)
README.mdQuick reference for the above—

The two-terminal model​

The scaffolding assumes a Project Manager (orchestrator) driving a development team in one terminal, and a Leader Agent running a research team in a second terminal. The PM delegates cross-terminal work by dropping a request file and activating the other terminal; the Leader Agent answers by writing a response file back.

Request / response flow​

  1. The PM writes a request to .agent-comms/requests/REQ-{timestamp}.md.
  2. The PM activates the Leader Agent in the other terminal — in TermFlow that is done with the MCP execute_command tool (see Connect an agent).
  3. The Leader Agent reads new files from requests/, does the work, and writes a report to .agent-comms/responses/RESP-{timestamp}.md.
  4. The PM polls responses/ for the reply and continues.

The generated README.md and (unless suppressed) docs/multi-team-agent-workflow.md document a simple Markdown message format:

# Research Request
**ID:** REQ-YYYYMMDD-NNN
**From:** Project Manager
**To:** Leader Agent
**Priority:** HIGH | MEDIUM | LOW
**Status:** PENDING
## Description
...
## Expected Output
...
# Research Response
**ID:** RESP-YYYYMMDD-NNN
**Request ID:** REQ-YYYYMMDD-NNN
**From:** Leader Agent
**Status:** COMPLETE | PARTIAL | FAILED
## Summary
...
## Detailed Findings
...

These formats are conventions, not enforced schemas — the files are ordinary Markdown that any agent can read and write.

tip
  1. Run tk init (add --no-docs if you only want the folders).
  2. Delete or ignore the generated .mcp.json and .gemini/settings.json.
  3. Open TermFlow → Settings → Connections → "Connect an AI agent" and paste the config it generates for your client (server key auto-terminal, URL http://127.0.0.1:42032/mcp). See Connect an agent.
  4. Keep .agent-comms/ as your agents' shared message bus.

Getting tk​

tk is built from the TermFlow source repository. From a checkout, inside the terminal-kit/ directory, build it and link a global tk command:

cd terminal-kit
npm install
npm run build
npm link

This registers tk on your PATH. It requires Node.js 18 or newer.

Next steps​