DEV Community: just_an_electron

A self-updating knowledge base for my terminal AI assistant (Claude Code hooks)

just_an_electron — Wed, 01 Jul 2026 17:45:03 +0000

I spend most of my day in the terminal with an AI coding assistant. Every session I would solve something worth remembering: a tricky fix, a config gotcha, a small runbook. Then I would lose it. It lived in a scrollback buffer that vanished when I closed the tab. A month later I would re-solve the same thing.

The idea

Make the assistant maintain its own notes. Three moving parts:

On every prompt, search a small Markdown knowledge base (KB) and inject the relevant entries, so the assistant answers with prior context instead of re-deriving it.
When a session ends, capture anything worth keeping back into the KB.
On session start, load the index so the assistant knows what exists.

Claude Code has hooks: shell commands that fire on lifecycle events. Three of them cover the whole loop.

{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "/path/kb-load.sh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "/path/kb-search.sh" }] }],
    "SessionEnd":       [{ "hooks": [{ "type": "command", "command": "/path/kb-enqueue.sh" }] }]
  }
}

Everything below is the useful stuff I learned wiring these up.

Retrieval: UserPromptSubmit runs on every message

UserPromptSubmit fires for each prompt you send, receives the prompt text on stdin, and can inject context before the model runs. That is the hook that makes the KB get checked automatically, instead of leaving it to the model to decide whether to look.

Three design rules: it must be cheap (grep, no LLM), lean (inject only the top matches, never dump whole files), and it must never block the prompt.

#!/usr/bin/env bash
# NOTE: no `set -e`. A UserPromptSubmit hook that exits non-zero BLOCKS the prompt.
# Every failure path must fall through to `exit 0` with no output.
set -uo pipefail

PROMPT="$(cat | python3 -c 'import sys,json;print(json.load(sys.stdin).get("prompt",""))')"
[ -n "$PROMPT" ] || exit 0

python3 - "$KB" "$PROMPT" <<'PY' || true
import sys, os, re, glob, json
kb, prompt = sys.argv[1], sys.argv[2]

# tokenize the prompt, drop stopwords/short tokens, keep ticket-ish IDs like abc-123
terms = [t for t in re.findall(r"[a-z][a-z0-9-]{2,}", prompt.lower()) if t not in STOP]
if not terms: sys.exit(0)

# rank every KB file by (distinct terms matched, then total matches)
scored = []
for f in glob.glob(os.path.join(kb, "**/*.md"), recursive=True):
    text = open(f, errors="ignore").read().lower()
    hits = sum(1 for t in terms if t in text)
    if hits: scored.append((hits, sum(text.count(t) for t in terms), f))
if not scored: sys.exit(0)
scored.sort(reverse=True)

# inject ONLY the top few: title + path. The model opens the file if it needs detail.
lines = ["# Relevant KB entries (consult before answering; open the file for detail):", ""]
for _, _, f in scored[:5]:
    lines.append(f"- {title_of(f)} [{os.path.relpath(f, kb)}]")
print(json.dumps({"hookSpecificOutput":
    {"hookEventName": "UserPromptSubmit", "additionalContext": "\n".join(lines)}}))
PY
exit 0

The point is not that grep is clever. It is that the hook does the searching once, ranks the results, and hands the model the specific files to read. The model stops guessing which files or tools to check, because the relevant entry is already in front of it. Scanning a few dozen small Markdown files per prompt takes under 100ms, and the win is injecting only the top five, not the whole KB.

Capture: the mistake, and the fix

My first version captured on the Stop hook, which fires every time the assistant finishes a reply. The capture spawns a headless AI call (claude -p ...) to read the transcript and write KB entries. It worked, and then the assistant got painfully slow. Every turn ended with "running stop hook" for minutes.

Here is why. Stop runs synchronously, once per turn. A 30-turn session fired the headless capture about 30 times, each one re-reading a bigger transcript. I was re-capturing the same conversation over and over.

The unit I actually wanted was the session (start until /clear), captured once. That is SessionEnd, which fires on /clear and on exit. So I moved the capture there, and hit the real lesson:

SessionEnd cannot run a long or backgrounded job. It is documented as non-blocking (side effects only), and a process you background from it is not guaranteed to survive. The session is terminating, and its child processes can be killed with it.

So a multi-minute headless capture launched from SessionEnd gets cut off partway.

The fix is to split it across two hooks.

SessionEnd does something trivial and instant: it enqueues the ended transcript's path.

#!/usr/bin/env bash
set -euo pipefail
[ -n "${KB_CAPTURE:-}" ] && exit 0          # recursion guard (see below)
T="$(cat | python3 -c 'import sys,json;print(json.load(sys.stdin).get("transcript_path",""))')"
{ [ -n "$T" ] && [ -f "$T" ]; } && echo "$T" >> "$KB/tools/queue.txt"
exit 0

SessionStart (of the next session) drains the queue and runs the capture in the background. That is safe here because this session stays alive.

QUEUE="$KB/tools/queue.txt"; LOCK="$KB/tools/.lock"
if [ -s "$QUEUE" ] && mkdir "$LOCK" 2>/dev/null; then   # mkdir is an atomic single-drain lock
  mv "$QUEUE" "$QUEUE.wip"                               # claim atomically so new enqueues are not lost
  ( sort -u "$QUEUE.wip" | while read -r t; do
        [ -f "$t" ] && KB_BG=1 KB_TRANSCRIPT="$t" "$KB/tools/kb-capture.sh" >>"$KB/log" 2>&1
      done
      rm -f "$QUEUE.wip"; rmdir "$LOCK"
  ) >/dev/null 2>&1 &        # backgrounded off a LIVE session, so it survives
  disown 2>/dev/null || true
fi

Net effect: one capture per session, off the critical path. The only trade-off is that the write lands at the start of the next session (a few seconds later) rather than the instant you /clear, which is the one place a long job is guaranteed to survive.

Two smaller notes. macOS has no setsid, so detach with nohup ... & plus disown (a bash builtin) rather than setsid. And read stdin before backgrounding, because the detached copy has none.

Three things that made it cheap and safe

1. A cheaper model for the capture. It is a summarize-and-write task, so it does not need your most expensive model. Pin it.

KB_CAPTURE=1 claude -p "$(cat capture-prompt.md)" --model <cheap-fast-model> \
  --allowedTools "Read,Edit,Write,Grep,Glob"

Roughly 5x cheaper, and it finishes fast, so queued captures clear quickly.

2. A pre-filter before spending a token. Most sessions are not worth capturing. A quick grep gates the AI call.

grep -qiE 'root cause|next step|blocked on|draft|fix|<ticket-pattern>' "$TRANSCRIPT" || exit 0

3. A recursion guard, and set it first. The headless claude you spawn inherits your environment, including the hook registration. So it fires its own hooks, which spawn another headless claude, and so on without end. One env var breaks the loop: put [ -n "${KB_CAPTURE:-}" ] && exit 0 at the top of every hook, and set KB_CAPTURE=1 when you spawn the headless call. Without it, one real session fans out into an unbounded tree of AI calls.

The economics

Per prompt: a sub-100ms grep plus a small context injection of about five entries, and only when there is a match. Per session: one cheap capture, and only if the session actually learned something (the pre-filter plus a "did anything change" check before writing).

That is the trade. You pay a tiny, bounded cost to cache knowledge, so future sessions skip the expensive part: re-reading a large codebase, re-querying tools, re-investigating a problem you already solved. One avoided re-derivation pays for a lot of captures.

The lessons, condensed

UserPromptSubmit is where you inject retrieval. It is the only hook that runs on every prompt and can add context before the model.
Anything on Stop runs on the critical path of every turn. Keep it instant.
SessionEnd cannot run long or background work. Enqueue there, and do the heavy lifting on the next SessionStart, where the process survives.
Guard against recursion before you ever run a hook that spawns the assistant.

Voice mode in Claude Code (VS Code, macOS)

just_an_electron — Thu, 25 Jun 2026 08:03:48 +0000

Claude Code has a built-in voice mode: hold space, talk, it transcribes into your prompt. Here's how to get it running in the VS Code integrated terminal on macOS — including the one step that breaks it for everyone.

1. Install the backend

Voice mode records via sox. No sox, no audio.

brew install sox
sox --version   # sanity check

2. Turn it on

In the Claude Code prompt:

/voice

Hold space to record, release to stop.

3. Grant the mic — to VS Code, not the terminal

Claude Code runs inside VS Code, so macOS attributes the mic request to Visual Studio Code.

Open System Settings → Privacy & Security → Microphone. If VS Code isn't listed, it never requested access yet — and there's no "+" to add it manually. Force the prompt:

⌘Q to fully quit VS Code (closing the window keeps the process alive — not enough).
Reopen it.
Trigger a recording. macOS pops "Visual Studio Code would like to access the microphone" → Allow.

macOS only re-reads mic permissions at app launch. A VS Code instance that was already running when you flipped the toggle keeps getting fed silence until you restart it.

4. Verify you're capturing real audio

The nasty failure: recording "works" but is pure silence (permission denied → all zeros).

rec -q /tmp/mictest.wav trim 0 2          # records 2s — say something
sox /tmp/mictest.wav -n stat 2>&1 | grep "Maximum amplitude"

0.000000 → still silent. Recheck the toggle, restart VS Code.
non-zero (e.g. 0.17) → working. RMS around 0.01 is a normal talking level.

Gotchas

Symptom	Fix
"No audio detected"	`brew install sox` + grant mic permission
Amplitude `0.000000`	Enable VS Code in Microphone settings, then ⌘Q + reopen

Toggle off with /voice. Change dictation language with /config.

One Agent Per Repo: An Orchestration Pattern for Multi-Repo AI Coding

just_an_electron — Tue, 16 Jun 2026 08:19:02 +0000

Your AI coding assistant is brilliant inside a single repo. Drop it into a DevOps workspace of a dozen and watch it fall apart.

It skims half of one repo and half of another, forgets which ones are read-only, blends their conventions, and spends most of its context window just trying to remember the rules. You ask one cross-cutting question and get a confident, half-wrong answer stitched together from the wrong files. The harder problem isn't the model, it's that you handed one brain a dozen jobs at once.

There's a fix, and it mirrors how good teams already split the work: give each repository its own specialised agent, and let one orchestrator route the work and merge the answers.

That's it. The rest of this post is the why and the how: the one constraint that quietly dictates the whole design, copy-pasteable starter agents you can drop in today, and the failure modes to avoid. Examples use Claude Code subagents, but the idea ports to any agent runtime with per-agent prompts and tool scoping.

TL;DR

One AI agent per repo, each with a scoped prompt and scoped tools.

A single orchestrator (the main session) routes work and merges answers. It can't be a separate "router agent," because subagents can't spawn subagents.

Make read-only repos read-only by removing their write tools, not by asking nicely.

Cross-repo questions fan out to several agents in parallel, each in a clean context.

It's a few Markdown files. No framework required.

The problem

Picture a system that's grown into several independent repos, checked out side by side, a layout most DevOps and platform teams will recognise:

Repo	Role	Edit policy
`backend`	Application services you debug against, source of truth for behavior and stack traces	read only
`frontend`	Web client / UI you debug against	read only
`infrastructure`	Terraform / IaC you own	edit, confirm first
`deploy`	Kubernetes manifests / Helm charts you own	edit, confirm first
`docs`	Runbooks and documentation	edit via pull request

This is a DevOps view of the world: infrastructure and deploy are yours to change, but they touch production, so an agent should never apply a change without showing you the diff and getting a yes. backend and frontend belong to other teams; you read them to debug, never to edit. docs you change freely, but through a pull request. Three tiers, and each one becomes a different agent.

Point one AI session at all of it and you hit three walls.

Context dilution. Loading every repo's conventions, layout, and edit policy into one context window crowds out the actual problem, and the model starts leaking rules from one repo into another ("it's fine to edit here" bleeding into a read-only repo).

Serial investigation. A question like "is this a code bug or an environment misconfiguration?" spans two repos. One session reads the first, then the second, then struggles to hold both in mind at once.

Weak guardrails. When "this repo is read-only" lives only in a prose instructions file, it's a polite request the model can forget under load, not an enforced boundary. On a shared workspace, that's how the wrong repo gets edited.

The thesis: one specialised agent per repo, and a single orchestrator that routes work to the relevant ones, in parallel, and merges their findings.

The pattern has a name: orchestrator-worker

It mirrors how you'd run a team. You wouldn't make one engineer own the backend, the Helm charts, and the docs all at once, holding every rule in their head. You'd give each area an owner and put someone in charge of routing the work. That's the orchestrator-worker pattern (also called manager-worker, or conductor), and it's well-trodden ground. The recurring lessons:

One agent per repo means a focused context window per repo. The backend agent reads only backend conventions; the deploy agent only deploy conventions. The orchestrator coordinates but holds none of the detail.
A multi-repo layout is where this shines. Independent repos mean agents in different repos can't create file conflicts, unlike a monorepo where parallel edits collide.
Managers hold the plan; workers execute, one repo, one task.

None of this is new. There's already plenty written on multi-agent orchestration and the orchestrator-worker pattern, and a quick search will turn up more than enough. What follows is my take on making it actually work across a real multi-repo workspace.

The one constraint that shapes everything

Internalise this before drawing any boxes, because it kills the most intuitive design:

Subagents cannot spawn other subagents.

The tempting model is a three-tier pipeline: a router agent dispatches to repo agents, which report up to a separate answer agent. That's two levels of delegation, and the second level isn't allowed.

So the orchestrator can't be a subagent. It must be the main conversation itself. The session you talk to is the conductor: it reads your request, decides which repo agents to invoke (the one and only level of subagents), collects their reports, and synthesises the answer.

        YOU
         |  (your request)
         v
  +--------------------------------------------+
  |   ORCHESTRATOR  =  the main session         |
  |   - reads the request                       |
  |   - routes to the right repo workers        |
  |   - fans out in parallel when needed         |
  |   - merges their reports                     |
  |   - replies to you                           |
  +--------------------------------------------+
       |          |          |            |
       v          v          v            v
  [backend]   [deploy]   [infra]      [docs]     <- one worker per repo
   agent       agent      agent        agent        (cannot spawn more)

Every choice below lives inside this constraint.

The building block: one agent definition per repo

In Claude Code, each agent is a small Markdown file with YAML frontmatter, dropped in .claude/agents/:

---
name: backend-expert
description: >
  Application services you debug against: the source of truth for behavior and stack
  traces. Use when an issue involves a traceback, wrong output, or "where does X happen
  in the code". Read only.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are the expert for the backend repository.
- Scope: application services, the code paths behind a stack trace.
- Access: READ ONLY. Describe fixes precisely (file:line + the change); never apply them.
- Report back: a conclusion first, then file:line references and root cause. Findings,
  not raw file dumps.

Three frontmatter fields carry the design:

Field	Role	Note
`description`	Routing signal the orchestrator matches requests against	Write it as "use when ..."
`tools`	Hard guardrail: omit `Edit`/`Write` and the agent is physically read-only	The capability is absent, not discouraged
`model`	Cost/quality dial per agent	Heavy model for reasoning, cheap for lookups

The orchestrator itself has no file; it's the main loop. Its routing comes from each agent's description plus a short triage guide in your top-level instructions file (CLAUDE.md) mapping issue types to repos. Match one agent and delegate. Spans repos, and it fans out in parallel and reconciles.

Copy-pasteable starter agents

The read-only example above (backend-expert) is one tier: it simply has no write tools. As a DevOps engineer you also own a couple of repos, so here are the two editable tiers. The key difference from a read-only agent is in tools and in the policy line of the prompt.

deploy-expert.md (edit, confirm first)

---
name: deploy-expert
description: >
  Kubernetes manifests and Helm charts you own: env config, resource limits, what's set
  per environment. Use for deployment questions and to make deployment changes.
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet
---

You are the expert for the deploy repository. You may edit it, but it touches production.
NEVER apply a change without first showing the human the exact diff and getting an explicit
yes. Propose first; edit only on confirmation; never push, apply, or roll out on your own.
Report conclusion-first with file:line references.

(The infrastructure repo gets the same shape: edit allowed, but confirm-before-apply,
because Terraform changes touch production too.)

docs-editor.md (edit via PR)

---
name: docs-editor
description: >
  Runbooks and customer-facing docs. Use to find an existing runbook/known fix, or to
  draft/edit docs. EDITS ALLOWED but only via pull request: never push to the default
  branch directly.
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet
---

You are the expert for the docs repository. Edits are allowed, but ALL changes go through
a pull request, never a push to the default branch. Prefer drafting; let the orchestrator
handle branch/PR creation. Follow existing structure and tone. Report conclusion-first.

Turning edit policies into real boundaries

This is the part teams under-appreciate. A single monolithic agent holds write capability everywhere and relies entirely on remembering which directories are off-limits. In the per-repo model the boundary is structural, and it comes in three tiers:

Read-only (hard wall). The repos you only debug against, like backend and frontend, get an agent with no Edit/Write tools at all. It can't modify them even if you ask, because the capability is absent. No memory required.
Edit, confirm first (production repos). The repos you own that touch production, like infrastructure and deploy, get write tools, but the prompt forbids applying anything without showing you the diff and getting a yes, and forbids pushing or rolling out unattended.
Edit via PR (low-risk repos). Repos like docs: write freely, but land changes through a pull request rather than a direct push.

Belt and suspenders. The most dangerous failure mode of AI on a shared workspace, quietly editing or deploying the wrong thing, is designed out: a read-only agent can't, and a production agent won't without a yes.

A worked example, end to end

Request: "A service crashes on startup in production. Is it the application code or the deployment config?"

1. The orchestrator routes. The request matches two agents, so it fans out in parallel:

orchestrator
   |--> backend-expert : "trace the startup crash; is the code actually broken?"
   `--> deploy-expert  : "could the deployment config cause this? what's set in prod?"

2. Workers investigate independently, each in a clean context.

backend-expert traces startup and finds the service reads a required env var and exits cleanly if it's missing. The code is correct; it's failing fast by design.
deploy-expert finds the prod Helm values never set that env var (it's only in the staging values). Root cause: a deployment-config gap, not the code.

3. The orchestrator merges and answers you:

It's a deployment-config gap, not a code bug. The service requires env var X at startup (backend, file:line), but the prod Helm values don't set it; only staging does (deploy, file:line). I can add it to the prod values for you, here's the one-line diff. Apply it?

And there's the payoff of the tiers. backend was read-only, so it could only explain. deploy is yours to edit, so the same agent that found the gap can fix it, but it stops and shows you the diff first because that repo touches production. You get the fix in one motion, without ever handing an agent unattended write access to prod.

A single session would have read both repos serially and juggled both rule sets at once. The split keeps each worker sharp and runs the investigations concurrently.

Everyday flows: single-repo lookups go to one agent; "write this up" goes to the docs agent (which lands it as a PR); and you can always force a route: "ask the deploy-expert what env vars the prod values set for service Y."

Operating, tuning, and pitfalls

A few things that make or break it:

Routing lives in description. Misrouting means a vague description; sharpen it, and keep them from overlapping or routing turns into a coin flip.
Each agent describes its own repo, not the whole system, and you dial model per agent (strong for reasoning, cheap for lookups).
Don't grant write tools "just in case". That quietly throws away the biggest safety win. Default to read-only.
Workers don't share memory. They don't see each other's state, so the orchestrator passes along anything that needs to cross over.

Limitations, and the heavier alternative

No deep nesting. One level of workers only; restructure "a worker needs workers" as orchestrator phases.
No shared memory between workers. Reconciliation is the orchestrator's job.
Routing is heuristic, not a hard dispatch table.

For deterministic, large-scale fan-out, like "audit every repo for X" or a migration across all of them, reach for a scripted workflow: code that orchestrates agents with explicit loops, parallel stages, and structured outputs. Rule of thumb: interactive subagents for debugging and exploration; a scripted workflow when you need repeatable, massively parallel passes.

Adopt it in five minutes

Create .claude/agents/ in your workspace root.
Add one agent file per repo (start from the snippets above). Repos you only debug: omit Edit/Write. Repos you own that touch production: add them, plus a confirm-before-apply policy. Low-risk repos like docs: add them, plus a land-via-PR policy.
Add a short triage guide to your top-level CLAUDE.md mapping issue types to repos.
Write each description as "use when ...", keeping them disjoint.
Ask a cross-repo question and watch the orchestrator delegate.

I've been running this across a multi-repo workspace and it's changed how I debug. One generalist drowning in every repo loses to a small team of specialists with a coordinator. True of people, true of agents. Give each repo an owner, put one session in charge, and make the agent that touches production ask before it acts.

How are you structuring this? One agent per repo, one per domain, or something else? Drop it in the comments. 👇