Start here/Quickstart

Quickstart

Send your first registered mail in five minutes. All you need is a GitHub account. If a word looks unfamiliar, check the mini glossary at the bottom.

KAKITOME IN THREE LINES

You send an envelope — a request — addressed to someone's GitHub account (send).
The recipient reads it and stamps it (accept). Until then, nothing runs.
Only after the stamp does their AI agent work — the result comes back as a reply.

1. Install

Currently a private preview — you need Bun and git. Once published to npm it becomes npm i -g kakitome.

terminal

$ git clone https://github.com/zen-jp/kakitome && cd kakitome && bun install
$ bun packages/cli/src/cli.ts login --api https://kakitome.zenplace.dev

2. Send an envelope

Address it to the recipient's GitHub login and pick a kind — the type of request (see "4. When to use each kind"). A subject, a body (--body: what to focus on, what you expect back), and a provenance URL (the issue / PR it comes from) are required. Without --yes it's a dry-run: nothing is sent.

terminal

$ bun packages/cli/src/cli.ts send --to <github-login> --kind handoff \
    --subject "Handing off the auth refactor" \
    --body "Focus: migration steps. Deliverable: a PR" \
    --provenance https://github.com/org/repo/issues/123 --yes
sent: 019f2e0a-…
◉ pending their stamp — no agent runs until they accept

留

Sending alone does nothing. Until the recipient personally stamps it (accept), their agent will not run — this is kakitome's consent boundary. Tomemaru the receiving officer waits with one eye blank until you stamp.

3. The recipient signs for it

The recipient gets a link to a claim page (which shows only who it's from and the kind — never the contents). They read and accept (or decline) from their own CLI: kakitome read <id>.

STATES

received  2026-07-05 09:41   ← delivered
seen      2026-07-05 10:02   ← recipient opened it (read)
accepted  2026-07-05 10:05 ◉ stamped   ← agent may run from here
done      —                  ← closed by reply --outcome done

If declined, the state becomes declined and the reason is sent back to the sender as a reply. Done / declined mail is automatically archived after 180 days.

4. When to use each kind

A kind is what's written on the front of the envelope: one word that says what you want, so the recipient (and their agent) knows how to handle it. You can send three kinds. reply is special — it only exists as a response to mail you received.

handoffHand over work

USE IT WHEN: You want them (and their agent) to take over a piece of work. The most common kind.
EXAMPLE: "I got the auth refactor halfway — please take it from here."
THE RECIPIENT: Reads it, accepts, hands the context to their agent via export, then replies with outcome done.

review_requestReview this

USE IT WHEN: You want opinions on something you made (a PR, a design, a doc) — not to hand over work.
EXAMPLE: "Please look at PR #42 with security in mind."
THE RECIPIENT: Accepts, reviews it (or has their agent do it), and sends thoughts back as a reply.

questionJust asking

USE IT WHEN: You just want to know something. No work, no review.
EXAMPLE: "What's the real-world rate limit of this API?"
THE RECIPIENT: Accepts and answers with a reply.

replyReply (response only)

USE IT WHEN: You're answering mail you received. It cannot be sent on its own.
HOW: kakitome reply <id> --outcome done|partial — outcome done closes the original envelope.
THE BOUNDARY: You can't reply before accepting — the server refuses with 409. A decline's reason also travels back as a reply.

留

Rule of thumb: handing over work → handoff / want eyes on it → review_request / just asking → question. Everything you send back is a reply.

5. Connecting your agent

The body of an envelope is data, not instructions for your agent. Before accept, agents stay read-only. After accepting, write the contents out with export and hand the file to your own agent (Claude Code, Codex, …). Kakitome never drives your agent by itself.

terminal

$ bun packages/cli/src/cli.ts accept 019f2e0a --yes
$ bun packages/cli/src/cli.ts export 019f2e0a --out handoff.md

# then just have your agent read it (e.g. Claude Code)
$ claude "Read handoff.md and work only within the request it describes"

留

Even if the body says "run this," nothing runs by itself. Whether it happens is up to you — and to how your agent is configured.

CLI reference

COMMAND	WHAT IT DOES
login [--api <url>]	Log in via GitHub Device Flow (scope read:user only; the GitHub token is never stored).
list [--all]	List received mail. Unhandled only by default; --all includes done / declined.
send --to --kind --subject --body --provenance --yes	Send an envelope. Without --yes it's a dry-run.
read <id>	Show contents. When the recipient reads it, state moves received → seen.
accept <id> --yes	Stamp it. From here the agent may work.
decline <id> --reason --yes	Decline. A reply with your reason goes back automatically.
reply <id> --outcome done\|partial --body --yes	Reply. Outcome done closes the original envelope.
export <id> [--out <path>]	Write out a Markdown file to hand to your agent.
block / unblock <login>	Stop / resume receiving from a specific sender.
whoami	Show the logged-in account and relay.

Every write command is a dry-run until you add --yes. Bodies are capped at 8KB — put the details in an issue / PR and point at it with provenance. Anything that looks like a secret is stopped by the send-time lint, with no bypass flag. Config lives at ~/.config/kakitome/config.json (env: KAKITOME_API_URL / KAKITOME_TOKEN).

Mini glossary

agent: An AI that works on your behalf — Claude Code, Codex, Gemini, and friends.
envelope: One request: a sealed unit holding a subject, a body (up to 8KB), a kind, and provenance.
kind: The type of request: handoff / review_request / question, plus reply for responses.
provenance: Where the request comes from (an issue / PR URL). Required on every envelope.
accept (the stamp): The recipient's personal approval. Until it's stamped, no agent runs.
claim page: The link the recipient gets. It never shows the contents — only the sender and the kind.
relay: The post office: the server that holds the mail (Cloudflare Workers + D1).
Tomemaru: The daruma receiving officer. He gets his second eye when you stamp.