Files
skills/public/coding-agent.html
zeekay fec2bdf0d1 The skills index lists a skill only when the site serves it whole; the build drops pages with no source
site.py now lists a SKILL.md under skills/ only when /<name>.md is that
file byte for byte and every file it points at by a relative path
(references/, scripts/, templates/, tools/, a sibling page) is published.
120 entries pointed at files the site does not serve, reference docs were
listed as skills, and 18 names served another file. 188 skills remain.
tests/discovery.py holds the published index to the same rule.

build.py deletes every page it did not write, except the hand-written
pages in KEEP, walks skills/ in name order so a shared name resolves the
same on every filesystem, and refuses to run without HIPS_DIR. Rebuilt
against hanzoai/hips main: the 40 discover-* pages and 20 HIPs whose
source is gone are removed, the stale code-review, engineering-code-review
and ml pages match their source, and 66 pages that were never built (60
skills among them) and 4 new HIPs are published. .gitignore anchors the root symlinks, so public/gemini.md is
not ignored on a case-insensitive checkout.
2026-10-29 21:28:54 -07:00

373 lines
25 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>coding-agent</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/coding-agent">
<link rel="alternate" type="text/markdown" href="/coding-agent.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/coding-agent.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>coding-agent</h1><p class="lede">Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:&quot;acp&quot;), or any work in ~/clawd workspace (never spawn agents here). Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required.</p><h1>Coding Agent (bash-first)</h1>
<p>Use <strong>bash</strong> (with optional background mode) for all coding agent work. Simple and effective.</p>
<h2>⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no</h2>
<p>For <strong>Codex, Pi, and OpenCode</strong>, PTY is still required (interactive terminal apps):</p>
<pre><code class="lang-bash"># ✅ Correct for Codex/Pi/OpenCode
bash pty:true command:&quot;codex exec &#x27;Your prompt&#x27;&quot;</code></pre>
<p>For <strong>Claude Code</strong> (<code>claude</code> CLI), use <code>--print --permission-mode bypassPermissions</code> instead. <code>--dangerously-skip-permissions</code> with PTY can exit after the confirmation dialog. <code>--print</code> mode keeps full tool access and avoids interactive confirmation:</p>
<pre><code class="lang-bash"># ✅ Correct for Claude Code (no PTY needed)
cd /path/to/project &amp;&amp; claude --permission-mode bypassPermissions --print &#x27;Your task&#x27;
# For background execution: use background:true on the exec tool
# ❌ Wrong for Claude Code
bash pty:true command:&quot;claude --dangerously-skip-permissions &#x27;task&#x27;&quot;</code></pre>
<h3>Bash Tool Parameters</h3>
<p>| Parameter | Type | Description | | ------------ | ------- | --------------------------------------------------------------------------- | | <code>command</code> | string | The shell command to run | | <code>pty</code> | boolean | <strong>Use for coding agents!</strong> Allocates a pseudo-terminal for interactive CLIs | | <code>workdir</code> | string | Working directory (agent sees only this folder&#x27;s context) | | <code>background</code> | boolean | Run in background, returns sessionId for monitoring | | <code>timeout</code> | number | Timeout in seconds (kills process on expiry) | | <code>elevated</code> | boolean | Run on host instead of sandbox (if allowed) |</p>
<h3>Process Tool Actions (for background sessions)</h3>
<p>| Action | Description | | ----------- | ---------------------------------------------------- | | <code>list</code> | List all running/recent sessions | | <code>poll</code> | Check if session is still running | | <code>log</code> | Get session output (with optional offset/limit) | | <code>write</code> | Send raw data to stdin | | <code>submit</code> | Send data + newline (like typing and pressing Enter) | | <code>send-keys</code> | Send key tokens or hex bytes | | <code>paste</code> | Paste text (with optional bracketed mode) | | <code>kill</code> | Terminate the session |</p>
<hr>
<h2>Quick Start: One-Shot Tasks</h2>
<p>For quick prompts/chats, create a temp git repo and run:</p>
<pre><code class="lang-bash"># Quick chat (Codex needs a git repo!)
SCRATCH=$(mktemp -d) &amp;&amp; cd $SCRATCH &amp;&amp; git init &amp;&amp; codex exec &quot;Your prompt here&quot;
# Or in a real project - with PTY!
bash pty:true workdir:~/Projects/myproject command:&quot;codex exec &#x27;Add error handling to the API calls&#x27;&quot;</code></pre>
<p><strong>Why git init?</strong> Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.</p>
<hr>
<h2>The Pattern: workdir + background + pty</h2>
<p>For longer tasks, use background mode with PTY:</p>
<pre><code class="lang-bash"># Start agent in target directory (with PTY!)
bash pty:true workdir:~/project background:true command:&quot;codex exec --full-auto &#x27;Build a snake game&#x27;&quot;
# Returns sessionId for tracking
# Monitor progress
process action:log sessionId:XXX
# Check if done
process action:poll sessionId:XXX
# Send input (if agent asks a question)
process action:write sessionId:XXX data:&quot;y&quot;
# Submit with Enter (like typing &quot;yes&quot; and pressing Enter)
process action:submit sessionId:XXX data:&quot;yes&quot;
# Kill if needed
process action:kill sessionId:XXX</code></pre>
<p><strong>Why workdir matters:</strong> Agent wakes up in a focused directory, doesn&#x27;t wander off reading unrelated files (like your soul.md 😅).</p>
<hr>
<h2>Codex CLI</h2>
<p><strong>Model:</strong> <code>gpt-5.2-codex</code> is the default (set in ~/.codex/config.toml)</p>
<h3>Flags</h3>
<p>| Flag | Effect | | --------------- | -------------------------------------------------- | | <code>exec &quot;prompt&quot;</code> | One-shot execution, exits when done | | <code>--full-auto</code> | Sandboxed but auto-approves in workspace | | <code>--yolo</code> | NO sandbox, NO approvals (fastest, most dangerous) |</p>
<h3>Building/Creating</h3>
<pre><code class="lang-bash"># Quick one-shot (auto-approves) - remember PTY!
bash pty:true workdir:~/project command:&quot;codex exec --full-auto &#x27;Build a dark mode toggle&#x27;&quot;
# Background for longer work
bash pty:true workdir:~/project background:true command:&quot;codex --yolo &#x27;Refactor the auth module&#x27;&quot;</code></pre>
<h3>Reviewing PRs</h3>
<p><strong>⚠️ CRITICAL: Never review PRs in HanzoBot&#x27;s own project folder!</strong> Clone to temp folder or use git worktree.</p>
<pre><code class="lang-bash"># Clone to temp for safe review
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR &amp;&amp; gh pr checkout 130
bash pty:true workdir:$REVIEW_DIR command:&quot;codex review --base origin/main&quot;
# Clean up after: trash $REVIEW_DIR
# Or use git worktree (keeps main intact)
git worktree add /tmp/pr-130-review pr-130-branch
bash pty:true workdir:/tmp/pr-130-review command:&quot;codex review --base main&quot;</code></pre>
<h3>Batch PR Reviews (parallel army!)</h3>
<pre><code class="lang-bash"># Fetch all PR refs first
git fetch origin &#x27;+refs/pull/*/head:refs/remotes/origin/pr/*&#x27;
# Deploy the army - one Codex per PR (all with PTY!)
bash pty:true workdir:~/project background:true command:&quot;codex exec &#x27;Review PR #86. git diff origin/main...origin/pr/86&#x27;&quot;
bash pty:true workdir:~/project background:true command:&quot;codex exec &#x27;Review PR #87. git diff origin/main...origin/pr/87&#x27;&quot;
# Monitor all
process action:list
# Post results to GitHub
gh pr comment &lt;PR#&gt; --body &quot;&lt;review content&gt;&quot;</code></pre>
<hr>
<h2>Claude Code</h2>
<pre><code class="lang-bash"># Foreground
bash workdir:~/project command:&quot;claude --permission-mode bypassPermissions --print &#x27;Your task&#x27;&quot;
# Background
bash workdir:~/project background:true command:&quot;claude --permission-mode bypassPermissions --print &#x27;Your task&#x27;&quot;</code></pre>
<hr>
<h2>OpenCode</h2>
<pre><code class="lang-bash">bash pty:true workdir:~/project command:&quot;opencode run &#x27;Your task&#x27;&quot;</code></pre>
<hr>
<h2>Pi Coding Agent</h2>
<pre><code class="lang-bash"># Install: npm install -g @mariozechner/pi-coding-agent
bash pty:true workdir:~/project command:&quot;pi &#x27;Your task&#x27;&quot;
# Non-interactive mode (PTY still recommended)
bash pty:true command:&quot;pi -p &#x27;Summarize src/&#x27;&quot;
# Different provider/model
bash pty:true command:&quot;pi --provider openai --model gpt-4o-mini -p &#x27;Your task&#x27;&quot;</code></pre>
<p><strong>Note:</strong> Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!</p>
<hr>
<h2>Parallel Issue Fixing with git worktrees</h2>
<p>For fixing multiple issues in parallel, use git worktrees:</p>
<pre><code class="lang-bash"># 1. Create worktrees for each issue
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main
# 2. Launch Codex in each (background + PTY!)
bash pty:true workdir:/tmp/issue-78 background:true command:&quot;pnpm install &amp;&amp; codex --yolo &#x27;Fix issue #78: &lt;description&gt;. Commit and push.&#x27;&quot;
bash pty:true workdir:/tmp/issue-99 background:true command:&quot;pnpm install &amp;&amp; codex --yolo &#x27;Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.&#x27;&quot;
# 3. Monitor progress
process action:list
process action:log sessionId:XXX
# 4. Create PRs after fixes
cd /tmp/issue-78 &amp;&amp; git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title &quot;fix: ...&quot; --body &quot;...&quot;
# 5. Cleanup
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99</code></pre>
<hr>
<h2>⚠️ Rules</h2>
<ol><li><strong>Use the right execution mode per agent</strong>:</li></ol>
<ul><li>Codex/Pi/OpenCode: <code>pty:true</code></li><li>Claude Code: <code>--print --permission-mode bypassPermissions</code> (no PTY required)</li></ul>
<ol><li><strong>Respect tool choice</strong> - if user asks for Codex, use Codex.</li></ol>
<ul><li>Orchestrator mode: do NOT hand-code patches yourself.</li><li>If an agent fails/hangs, respawn it or ask the user for direction, but don&#x27;t silently take over.</li></ul>
<ol><li><strong>Be patient</strong> - don&#x27;t kill sessions because they&#x27;re &quot;slow&quot;</li><li><strong>Monitor with process:log</strong> - check progress without interfering</li><li><strong>--full-auto for building</strong> - auto-approves changes</li><li><strong>vanilla for reviewing</strong> - no special flags needed</li><li><strong>Parallel is OK</strong> - run many Codex processes at once for batch work</li><li><strong>NEVER start Codex in ~/.hanzo-bot/</strong> - it&#x27;ll read your soul docs and get weird ideas about the org chart!</li><li><strong>NEVER checkout branches in ~/Projects/hanzo-bot/</strong> - that&#x27;s the LIVE HanzoBot instance!</li></ol>
<hr>
<h2>Progress Updates (Critical)</h2>
<p>When you spawn coding agents in the background, keep the user in the loop.</p>
<ul><li>Send 1 short message when you start (what&#x27;s running + where).</li><li>Then only update again when something changes:</li><li>a milestone completes (build finished, tests passed)</li><li>the agent asks a question / needs input</li><li>you hit an error or need user action</li><li>the agent finishes (include what changed + where)</li><li>If you kill a session, immediately say you killed it and why.</li></ul>
<p>This prevents the user from seeing only &quot;Agent failed before reply&quot; and having no idea what happened.</p>
<hr>
<h2>Auto-Notify on Completion</h2>
<p>For long-running background tasks, append a wake trigger to your prompt so HanzoBot gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):</p>
<pre><code>... your task here.
When completely finished, run this command to notify me:
hanzo-bot system event --text &quot;Done: [brief summary of what was built]&quot; --mode now</code></pre>
<p><strong>Example:</strong></p>
<pre><code class="lang-bash">bash pty:true workdir:~/project background:true command:&quot;codex --yolo exec &#x27;Build a REST API for todos.
When completely finished, run: hanzo-bot system event --text \&quot;Done: Built todos REST API with CRUD endpoints\&quot; --mode now&#x27;&quot;</code></pre>
<p>This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.</p>
<hr>
<h2>Learnings (Jan 2026)</h2>
<ul><li><strong>PTY is essential:</strong> Coding agents are interactive terminal apps. Without <code>pty:true</code>, output breaks or agent hangs.</li><li><strong>Git repo required:</strong> Codex won&#x27;t run outside a git directory. Use <code>mktemp -d &amp;&amp; git init</code> for scratch work.</li><li><strong>exec is your friend:</strong> <code>codex exec &quot;prompt&quot;</code> runs and exits cleanly - perfect for one-shots.</li><li><strong>submit vs write:</strong> Use <code>submit</code> to send input + Enter, <code>write</code> for raw data without newline.</li><li><strong>Sass works:</strong> Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to the lead agent, got: _&quot;Second chair, I code / The lead sets the tempo / Keys glow, I follow&quot;_</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/coding-agent.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>