paperclip-kiro-adapter

A Paperclip adapter for the Kiro CLI. Install it into any Paperclip instance — no fork, no patched source — and your agents run on kiro-cli.

Adapter type key: kiro_local

Requirements

• Paperclip with external adapter support (Settings → Instance settings → Adapters)
• kiro-cli on the PATH of the machine running the Paperclip server
• A completed Kiro login (see below)

Install

From npm

Settings → Instance settings → Adapters → Install Adapter → npm package:

paperclip-kiro-adapter

Or through the API:

curl -X POST http://localhost:3100/api/adapters \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"packageName": "paperclip-kiro-adapter"}'

From a local checkout (development)

git clone https://github.com/Schapat/paperclip-kiro-adapter.git
cd paperclip-kiro-adapter
npm install && npm run build

Then Settings → Adapters → Install Adapter → Local path, pointing at the checkout. The directory is symlinked, so a rebuild plus a server restart picks up your changes.

Paperclip must be able to read the built dist/ — run npm run build before installing.

Log in to Kiro

Paperclip cannot perform the Kiro login for you. Run this once on the host, as the same user that runs the Paperclip server:

kiro-cli login --use-device-flow

The adapter's environment test reports whether the CLI is reachable and answering. If an agent run fails with an auth error, repeat the login.

Configuration

| Field | Default | Meaning | |---|---|---| | command | kiro-cli | Executable name or absolute path | | model | auto | One of the ids below; anything else is rejected by kiro at run time | | effort | — | Thinking effort: low, medium, high, xhigh, max | | cwd | workspace | Absolute working directory; normally left to Paperclip | | instructionsFilePath | managed | Path to the agent's AGENTS.md; Paperclip fills this in | | timeoutSec | 0 | Run timeout, 0 disables it | | graceSec | 20 | SIGTERM grace period | | logLineLimit | 2000 | Longest run-log line kept intact; 0 disables truncation | | promptTemplate | built-in | Overrides the heartbeat prompt; {{agent.id}}, {{cwd}}, {{taskContent}}, {{context.*}} are substituted | | extraArgs | — | Extra CLI arguments | | env | — | Extra environment variables |

Models: auto, claude-sonnet-4.6, claude-opus-4.5, claude-sonnet-4.5, claude-sonnet-4, claude-haiku-4.5, minimax-m2.5, minimax-m2.1, qwen3-coder-next.

auto is the default on purpose: without an explicit model kiro falls back to its own global chat.defaultModel, which aborts the run if that model is not available to your account.

Model ids are not Anthropic API ids. Agents that hire other agents write model as free text and reach for the dated ids they know, such as claude-sonnet-4-20250514 — nothing in Paperclip validates that field. The adapter translates the handful of aliases it recognizes (and says so in the log), and warns on the run when an id is one kiro does not offer at all. The valid ids are listed in the adapter's agent-configuration doc, which is what hiring agents read.

How it works

Agent profile. kiro-cli treats stdin as user input and flags Paperclip's instrumentation as a prompt-injection attempt. Each run therefore writes a temporary agent profile into kiro's global agent directory (~/.kiro/agents/paperclip-<runId>.json) carrying the Paperclip context as a trusted system prompt, and passes only the task message as the CLI's positional input. The file is removed when the run ends; leftovers from killed runs are swept after 24 hours.

The profile grants tools: ["*", …]. kiro's tools field is an allowlist, not a trust list — an empty array leaves the agent with no shell, read, or write tool at all, and it will narrate tool output it never produced. The wildcard covers the built-in tools; MCP servers are appended individually, see below.

Prompt assembly. The system prompt in the profile is built from the agent's skills, its AGENTS.md instructions, the session handoff note Paperclip supplies on a fresh session, and — when the heartbeat was triggered by a comment — an instruction to fetch and answer that comment first. Only the rendered heartbeat message goes in as the CLI's positional input.

MCP servers. Agents reach MCP from two sources, and both are wired up per run.

From kiro. includeMcpJson: true only puts the servers from kiro's mcp.json into the agent's configuration; their tools stay out of the agent's tool set, because "*" covers built-in tools only. MCP tools are addressed separately, as @server or @server/tool. Each run therefore reads the server names from ~/.kiro/settings/mcp.json and <cwd>/.kiro/settings/mcp.json and appends an @name entry per server, so anything you register with kiro-cli mcp add reaches the agent.

From Paperclip. The MCP connections configured inside Paperclip are handed to the adapter per run as { name, url, token } and written into the profile's mcpServers as HTTP servers with an Authorization: Bearer header — kiro sends those headers on the initialize request. Connection names are sanitized to what @name can address, and a name that kiro already configures is left alone rather than redefined.

Both sets are logged by name at the start of the run; tokens never reach the log.

Log output. kiro writes a terminal transcript and streams the assistant turn token by token. The adapter assembles whole lines before handing them to Paperclip, strips the escape codes, collapses carriage-return redraws, and truncates lines past logLineLimit. Only the log is affected — the run summary and session detection still see the original output.

Sessions. kiro-cli cannot report the session id of a run. After each run the adapter queries kiro-cli chat --list-sessions -f json and stores the newest session for that working directory, so the next heartbeat can resume it with --resume-id. Sessions older than the run are ignored, and the reported (resolved) path is matched against the run directory so a session is never adopted from elsewhere.

Transcripts. kiro renders a terminal transcript rather than a machine-readable stream. ui-parser.cjs classifies the rendered markers — assistant turns, tool calls with purpose and duration, diff rows, footer metrics — for hosts that load an adapter's UI parser. It is stateful, so continuation lines of an assistant turn are attributed correctly. Where the parser is not loaded, the sanitized log above is what you see.

Skills. Skills are ephemeral: there is nothing to install into kiro. The skills selected for an agent are read from Paperclip's runtime skills directory on every run and inlined into the system prompt as <skill name="…"> blocks, so a change to a skill takes effect on the next heartbeat. Missing skills are reported in the skills view rather than failing the run.

Environment. Beyond PAPERCLIP_API_URL and PAPERCLIP_API_KEY, each run exports what the heartbeat is about, so agent instructions and scripts can branch on it:

| Variable | Set when | |---|---| | PAPERCLIP_RUN_ID | always | | PAPERCLIP_TASK_ID | the wake concerns a task or issue | | PAPERCLIP_WAKE_REASON | the host reports one (e.g. issue_assigned) | | PAPERCLIP_WAKE_COMMENT_ID | a comment triggered the wake | | PAPERCLIP_APPROVAL_ID, PAPERCLIP_APPROVAL_STATUS | an approval triggered the wake | | PAPERCLIP_LINKED_ISSUE_IDS | the wake carries linked issues (comma-separated) | | PAPERCLIP_WORKSPACE_CWD | the run has a Paperclip workspace |

PAPERCLIP_API_KEY comes from the run's own auth token unless you set it explicitly in env.

API base URL. kiro runs on the Paperclip host, so its API calls go over loopback. A hosted Paperclip usually sets PAPERCLIP_API_URL to the public origin, which sits behind the reverse proxy's SSO and answers an agent's request with a login redirect instead of JSON. The adapter therefore overrides PAPERCLIP_API_URL for every run with http://<listen host>:<listen port> (from PAPERCLIP_LISTEN_HOST/HOST and PAPERCLIP_LISTEN_PORT/PORT, defaulting to http://127.0.0.1:3100), adds the loopback names to NO_PROXY, and names that base URL in the prompt. A non-local value is reported once in the run log. Set PAPERCLIP_LOCAL_API_URL on the Paperclip server if the API really lives somewhere other than loopback (a bridge or sidecar) — that value is used verbatim.

Environment test. The adapter's test checks the working directory, resolves the command, validates the configured model against kiro's ids, and then runs a real one-shot hello probe through kiro-cli — so a broken login surfaces as a failed probe with kiro's own error rather than as a mysterious run failure later.

Limitations

• No cost or token accounting. kiro-cli emits no usage data on a run (--format json covers only --list-models and --list-sessions), so Paperclip records zero spend for these agents and budget caps never trigger.
• Local execution only. The adapter runs kiro-cli on the Paperclip host; remote and sandboxed execution targets are not implemented.
• Login is manual, as described above.
• MCP servers scoped to another agent profile (kiro-cli mcp add --agent other) are invisible to the adapter. Register servers globally, per workspace, or in Paperclip itself.
• Upgrading needs a server restart, not just Reload adapter. Node caches ES modules per process, so a reload re-imports the entry point while its relative imports resolve to the already-loaded copies. When a release adds a new export, the reload fails with does not provide an export named … until the Paperclip server is restarted.

Development

npm install
npm run build
npm test
npm run typecheck

Tests run against captured real kiro-cli output rather than assumed formats. If kiro changes its rendering, src/output.ts and ui-parser.cjs both need updating — they are deliberate duplicates, because the UI parser must ship with zero imports.

License

MIT