This article was originally published in Japanese on Zenn.
Introduction
Hi, I'm Kohei Matsunobe, a second-year student at ZEN University studying Intelligent Informatics (online). I'm working toward becoming an engineer who builds and uses AI agents, and I do that through personal projects.
In October 2026, I built three open-source projects around AI agents.
| Name | In a sentence | Language |
|---|---|---|
| Yata (ヤタ) | A Japanese-first personal AI assistant that runs on your own PC | Python / TypeScript |
| kagi (鍵, "key") | A secret broker that keeps real API keys out of an AI agent's hands | Go |
| Omoikane (オモイカネ) | A screen that shows what Claude Code is doing, at a glance, in plain Japanese | TypeScript |
They may look like separate projects, but once I finished them, I realized they were all trying to answer the same question:
What do you need in order to trust an AI agent with real work?
My own answer is these three things:
- Stop them before a dangerous action (Yata's confirmation gate)
- Don't give them the keys in the first place (kagi)
- Make what they're doing visible (Omoikane)
This article covers the design decisions behind each one, and what I learned by building them.
I developed all three while consulting with Claude Code (the VS Code extension). I decide the direction of the design and what to build or not to build; implementation is a two-person effort with the AI.
1. Yata: An agent that can be stopped
https://github.com/koheip/yata
What it is
Yata is an AI assistant you talk to in chat, and it helps with work using web search, page reading, browser automation, Gmail/Calendar, LINE, and more. The name comes from Yatagarasu (八咫烏), the three-legged crow that guided Emperor Jimmu.
Here is what it does:
- Runs locally: conversations and memory are stored in SQLite on your PC
- You can choose the AI: Gemini / OpenAI / Anthropic / xAI / DeepSeek, plus local LLMs such as Ollama and LM Studio
- Connects to Japanese services: Chatwork, Backlog, kintone, freee, Money Forward Cloud Invoice, Rakuten Ichiba, LINE
- Japanese business calculations: public holidays, business days, the Japanese calendar (wareki), and consumption tax under the invoice system
- Routines: if you ask in chat to "summarize the news every morning at 8," APScheduler runs it every day
- Fully offline mode: uses only a local LLM and disables every tool that goes out to the network
Architecture
flowchart TB
UI["Chat UI<br/>React + TypeScript"]
API["FastAPI<br/>conversations, SSE, confirmation"]
Loop["Agent loop"]
Policy["ToolPolicy"]
Gate["ConfirmationGate"]
Router["ModelRouter"]
Registry["ToolRegistry"]
DB[("SQLite<br/>conversations and memory")]
UI -->|message| API
UI -->|approve / deny| Gate
API --> Loop
API --> DB
Loop --> Router
Loop --> Policy
Policy --> Gate
Loop --> Registry
The backend is Python (FastAPI), and the UI is React + TypeScript. The agent loop, Playwright, and SQLite live in the same process. Intermediate events (tool_call / tool_result / confirmation_required, and so on) are streamed to the UI over Server-Sent Events.
Design choice 1: Give tools a "risk," and let the loop just ask
A tool is a class with a name, a JSON Schema, a risk, and an execute function. I defined four risk levels.
| Risk | Examples | Handling |
|---|---|---|
read |
Search, page reading, reading Gmail | Run immediately |
write |
Saving local memory, drafting email | Run immediately |
mutate |
Browser clicks and typing | Confirm first |
external |
Sending email, creating or deleting events, payments | Confirm first |
The agent loop only asks ToolPolicy "does this tool need confirmation?" — it does not special-case individual tools. When you add a new dangerous tool, you register it with Risk.EXTERNAL and it joins the same confirmation flow.
The confirmation gate uses an asyncio.Future to connect the agent loop with an approval request from the UI.
class InMemoryConfirmationGate:
def __init__(self) -> None:
self._pending: dict[str, asyncio.Future[bool]] = {}
def open(self) -> str:
request_id = uuid.uuid4().hex
self._pending[request_id] = asyncio.get_running_loop().create_future()
return request_id
async def wait(self, request_id: str, timeout: float) -> bool:
future = self._pending.get(request_id)
if future is None:
return False
try:
return await asyncio.wait_for(future, timeout)
except TimeoutError:
return False # timeouts are treated as "deny"
finally:
self._pending.pop(request_id, None)
def resolve(self, request_id: str, approved: bool) -> bool:
future = self._pending.get(request_id)
if future is None or future.done():
return False
future.set_result(approved)
return True
Timeouts fall back to "deny." The policy is: when in doubt, don't run it.
If a dangerous tool is called from a routine (when nobody is looking at the screen), it does not run on its own. It stops in a "waiting for confirmation" state, and the next time you open the UI, you're asked to approve or deny. When you use it from LINE, the message shows "Approve" and "Deny" buttons.
Design choice 2: Skip the LLM wrapper, and put the differences where you can see them
I considered a unified wrapper like LiteLLM for swapping models, but this time I used the official SDKs (google-genai, openai, anthropic) directly.
The provider interface is a single complete(messages, tools, model). Vendor differences — especially how tool results are returned — are confined to one place: convert.py.
- OpenAI: a
tool-role message - Anthropic: a
tool_resultblock - Gemini: a
function_responsepart
A wrapper would mean less code, but more dependencies, and it becomes harder to see where and what is being converted. This is a personal project that also serves as learning and a portfolio, so I chose the option where the differences stay readable. OpenAI-compatible servers such as Ollama work just by changing the base_url.
Design choice 3: Minimize the surface that faces the outside
- Page reading inspects the URL on every redirect, and always rejects cloud metadata addresses (such as
169.254.169.254) - The LINE webhook is served on a separate server (port 8742) from the main UI (port 8741), exposing only
/line/webhook. Incoming requests are filtered with signature verification and a userId allowlist - Yata starts the cloudflared tunnel automatically, and re-registers the webhook URL with LINE whenever the URL changes
After building it: setup was far too hard
I published v0.1.0 and used it myself every day. The biggest problem wasn't the features — it was how hard setup was. Google integration in particular (creating an OAuth client in Cloud Console) and LINE integration (official account, channel, webhook) have so many steps that they're basically impossible for a typical person.
I've been chipping away at it — letting you paste API keys in the app, reducing install to a one-liner, automating the LINE tunnel — but the structure is still there: the more integrations you add, the more setup you get. That's the next problem to solve.
2. kagi: Don't give agents the keys
https://github.com/koheip/kagi
Why I built it
While building Yata, what worried me was how API keys get passed around. If you give a long-lived API key to an LLM agent as an environment variable, a prompt injection from a malicious web page or email could be enough to send the key outside.
So I built kagi, a broker that sits between the agent and the API, in Go. All the agent holds is an mTLS client certificate and a token that expires in a few minutes. The real key is injected by kagi at request time.
AI Agent ──mTLS + short-lived token──▶ kagid ──HTTPS + real key──▶ OpenAI, etc.
(does not know the key) │ token verification, allowlist
│ request caps, SSRF prevention
│ response redaction
└─ hash-chain audit log
It has zero dependencies (Go standard library only), which keeps the supply-chain attack surface small.
Mapping to the OWASP Top 10 for LLM
The design was about attaching a countermeasure to each of the recent problems, one by one.
| Problem | kagi's countermeasure |
|---|---|
| Secret leakage via prompt injection (LLM01/02) | The agent never knows the key. Even if the upstream echoes the key, it is redacted |
| Excessive privileges (LLM06) | Method + path allowlist (deny by default) |
| Unbounded consumption (LLM10) | Per-token request caps, per-agent rate limits |
| Token theft | Tokens are bound to the client certificate (in the spirit of RFC 8705) |
| SSRF / DNS rebinding | Block private destinations using the resolved IP after DNS lookup |
| Harvest now, decrypt later | Prefer X25519MLKEM768 (ML-KEM hybrid) on TLS 1.3 |
| Audit log tampering | An HMAC hash chain detects even a one-character change |
Design choice 1: Bind the token to the certificate
Tokens are signed with Ed25519 and include the SHA-256 thumbprint of the client certificate (the cnf claim). Even if a token leaks from a log, an agent with a different certificate can't use it.
== A different agent that stole the token tries to use it → 401 (certificate binding)
{"error":"token not bound to this client certificate"}
Design choice 2: Redaction that works across chunk boundaries
In case a real key ends up in an upstream API response (for example, echoed in an error message), kagi redacts keys from the response.
The hard part was streaming. SSE responses arrive in fragments, so if a key is split across two chunks, a naive replacement will miss it. I keep "key length − 1 bytes" to carry over into the next read, so matches that cross a boundary can still be detected.
mask(r.pend, r.secret)
keep := len(r.secret) - 1 // carry over the part that might cross a boundary
if r.eof {
keep = 0
}
if len(r.pend) > keep {
cut := len(r.pend) - keep
r.out = append([]byte(nil), r.pend[:cut]...)
r.pend = append([]byte(nil), r.pend[cut:]...)
}
In the tests, I feed the stream through iotest.OneByteReader so it is read one byte at a time, and confirm that it does not leak even under the worst splitting. Also, matches can't be detected in compressed responses, so kagi forces Accept-Encoding: identity on the upstream request.
Design choice 3: Encryption at rest, and "if it fails, stop"
- Secrets use envelope encryption: passphrase → (PBKDF2-SHA256, 600,000 iterations → HKDF) → KEK, and a DEK per secret (AES-256-GCM). The secret's name goes into the AAD, so ciphertext swapping can be detected
- Changing the passphrase only re-wraps the DEKs; the secrets' ciphertext does not change
- Fail-closed: if the audit log can't be written, the request is not executed
- Unknown fields in the policy are a load error (to prevent a typo from widening permissions)
If you run the demo script (./scripts/demo.sh), you can walk through everything from CA issuance to attack scenarios (key echoing, token theft, audit-log tampering).
Almost no change on the caller side
On the agent side, you just swap the OpenAI SDK's base_url and certificates.
client = OpenAI(
base_url="https://localhost:8443/v1/proxy/openai/v1",
api_key=token, # kagi's short-lived token (not the real key)
http_client=httpx.Client(cert=("pki/yata.crt", "pki/yata.key"), verify="pki/ca.crt"),
)
3. Omoikane: Make the agent's activity visible
It started as an orchestrator
I originally started Omoikane as an AI agent orchestrator. It splits Claude Code into "implementer → tester → test runner → reviewer," and a conductor assigns the work. The name comes from Omoikane-no-kami (思金神), the deity of wisdom who assigned roles to the gods in the myth of the Heavenly Rock Cave (Ama-no-Iwato).
At that stage I built mechanisms like these:
- Each role is run with
claude -p --output-format stream-json, and the output is read line by line and converted into common events - Test pass/fail is not self-reported by the role; Omoikane runs the test command itself and judges the result
- If tests or review fail, the work is sent back to the implementer, up to a retry limit
- Each role works on a dedicated branch in a git worktree, so it doesn't break your local work
- Before a merge, it always stops until a person presses "Approve"
- Besides Claude, the roles can be switched to ChatGPT / Grok / DeepSeek / Gemini
A change in direction: what really excited me was the visible screen
Along the way, I started to wonder: "Would I actually use this orchestrator in my own work?" Whether splitting into roles is really better is something I won't know until I evaluate it.
What I enjoyed most while building it, though, was the screen where the agent's activity streams by in real time. So I changed direction, and made the main feature a "watch UI" that reads the session logs of the Claude Code you already use, from the side.
npm run watch # watch your everyday Claude Code → http://localhost:4318
npm run watch:demo # try it without Claude Code
Omoikane only reads the JSON Lines under ~/.claude/projects. It writes nothing to Claude Code or to the logs.
Here's what you can see on the screen:
- Now: working, thinking, your turn, or stopped, plus a one-line status like "Rewriting a file: src/app.ts"
- Session list: an overview of multiple sessions on one screen
- Tokens and cost: a breakdown of input, output, and cache, plus counts per sub-agent
- Files touched and commands run: read/write counts, and whether commands succeeded
- Notifications: when it's your turn, when a question arrives, or when it might be stuck
Design choice 1: Don't use fs.watch; only read the appended part
File-change detection with fs.watch is unreliable depending on the OS, so I switched to polling every second. For each file I remember the position (offset) I've already read, and I read only the newly appended lines. For large files, I initially read only the last 8 MB and discard a truncated first line.
The log format changes a little with Claude Code versions, so unknown lines are silently skipped.
Design choice 2: Prevent double-counting tokens
Token display ran into a quirk of streaming. The same message's usage arrives many times, and output_tokens is a cumulative value. If you simply add them up, the numbers balloon several times over.
So I keep only the latest (maximum) value per message ID, and sum those. When a run finishes, I cross-check against the result event's modelUsage (which also includes smaller models used in the background).
export class TokenMeter {
private perMessage = new Map<string, Usage>();
observe(messageId: string, raw: RawUsage | undefined | null): void {
if (!messageId || !raw) return;
const prev = this.perMessage.get(messageId) ?? ZERO_USAGE;
// take the max instead of adding (output_tokens is cumulative)
this.perMessage.set(messageId, maxUsage(prev, fromRaw(raw)));
}
// on completion, cross-check against modelUsage
}
Design choice 3: Be honest that "might be stuck" is a guess
Claude Code's logs don't directly say whether it's waiting for permission. So when a tool result hasn't come back for 45 seconds for a command, or 20 seconds otherwise, the UI shows "It may be waiting for permission, or it may just be a long-running task." I made it clear in the UI and the README that this is a guess.
Putting the three together
Returning to the original question, the three tools divide the work like this:
flowchart LR
Human["Human"]
Agent["AI agent"]
Omoikane["Omoikane<br/>make it visible"]
Yata["Yata's confirmation gate<br/>stop them"]
Kagi["kagi<br/>don't give them the keys"]
API["External API"]
Agent -->|dangerous action| Yata
Yata -->|ask for approval| Human
Agent -->|short-lived token| Kagi
Kagi -->|inject the real key| API
Agent -.logs.-> Omoikane
Omoikane -.notify.-> Human
- Stop them: before a dangerous action, ask a person
- Don't give them the keys: don't give the agent things that would be a problem if they were stolen
- Make it visible: so a person can immediately see what's going on
My takeaway from building them is that any one of these isn't enough. Only in combination do you start to get closer to "I can trust this with the work."
What I learned by building them
- Safety is decided by the defaults: a timeout is a denial, an unknown field is an error, and if the audit log can't be written, you stop. If you build it so that, when in doubt, it falls toward the safe side, you have fewer things to worry about later
- Leave abstraction in the places where differences should stay visible: whether you're swapping LLMs or rendering an agent UI, if you define one common event type and confine vendor/tool differences to adapters, it's easier to change the internals later
- What you want to build is allowed to change as you build it: Omoikane shifted from an orchestrator to a watch UI, but the event conversion and Japanese-localization pieces I built for the orchestrator still carried over
- You don't know until you use it: the more features I added to Yata, the heavier setup became, and it got hard even for me to use. The first user is yourself
What's next
- Yata: reduce setup effort (make initial integration setup more automatic). Distribution via the Microsoft Store
- kagi: integration with Yata and Omoikane (borrow the key only when pushing or creating a PR). A setup where the actual keys live in AWS Secrets Manager
- Omoikane: compare solving a task with a single agent versus splitting it into roles, using an evaluation task set
Closing
All three are released under the MIT License (Omoikane is being prepared for release). I'd be very happy to get issues or feedback.
Top comments (0)