spb/khaelor Public
KHAELOR — a terminal-native autonomous engineering agent powered by Anthropic.
TypeScript 82.9%
HTML 14.9%
CSS 1.1%
JavaScript 0.7%
1<!doctype html>2<!--3KHAELOR4File: website/public/docs/worktrees.html5Description: Docs — Isolated parallel subtasks: git worktrees, child sessions, capability attenuation, supervised merges.6Author: Simon-Pierre Boucher7Contact: contact@spboucher.ai8-->9<html lang="en">10<head>11<meta charset="utf-8">12<meta name="viewport" content="width=device-width, initial-scale=1">13<title>Parallel worktrees — KHAELOR docs</title>14<meta name="description" content="Isolated parallel subtasks: git worktrees, child sessions, capability attenuation, supervised merges.">15<link rel="stylesheet" href="/styles.css">16<script>17(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})();18</script>19<script defer src="/site.js"></script>20</head>21<body>2223<header class="site-header"><div class="inner">24 <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a>25 <nav>26 <a href="/docs/getting-started.html">Docs</a>27 <a href="/#install">Install</a>28 <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button>29 </nav>30</div></header>3132<main class="page"><div class="docs-layout">3334<aside class="sidebar">35 <div class="group"><div class="group-title">Start</div>36 <a href="/docs/getting-started.html">Getting started</a>37 <a href="/docs/cookbook.html">Cookbook</a>38 </div>39 <div class="group"><div class="group-title">Using KHAELOR</div>40 <a href="/docs/usage.html">The TUI</a>41 <a href="/docs/commands.html">Commands & keyboard</a>42 <a href="/docs/tools.html">Tools</a>43 <a href="/docs/sessions.html">Sessions</a>44 </div>45 <div class="group"><div class="group-title">Autonomy</div>46 <a href="/docs/phases.html">Phase gates</a>47 <a href="/docs/verification.html">Verification</a>48 <a href="/docs/worktrees.html">Parallel worktrees</a>49 <a href="/docs/daemon.html">The daemon</a>50 </div>51 <div class="group"><div class="group-title">Intelligence</div>52 <a href="/docs/repograph.html">Semantic index</a>53 <a href="/docs/memory.html">Project memory</a>54 <a href="/docs/context.html">Context engine</a>55 <a href="/docs/fork-replay.html">Fork · replay · sdiff</a>56 </div>57 <div class="group"><div class="group-title">Control</div>58 <a href="/docs/permissions.html">Permissions</a>59 <a href="/docs/configuration.html">Configuration</a>60 <a href="/docs/cli.html">CLI reference</a>61 </div>62 <div class="group"><div class="group-title">Internals</div>63 <a href="/docs/architecture.html">Architecture</a>64 <a href="/docs/events.html">The event model</a>65 <a href="/docs/theming.html">Theming & terminal</a>66 </div>67 <div class="group"><div class="group-title">Help</div>68 <a href="/docs/faq.html">FAQ & troubleshooting</a>69 </div>70</aside>7172<article class="content">7374<h1>Parallel worktrees</h1>75<p class="lead">Run several tasks at once without ever letting an agent touch your working copy.</p>7677<h2 id="model">The isolation model<a class="anchor" href="#model">#</a></h2>78<p>Every <code>/spawn</code> creates:</p>79<ol>80 <li>a git worktree at <code>.khaelor/worktrees/<taskId></code> on branch <code>khaelor/<taskId></code>;</li>81 <li>a <strong>child session</strong> — its own JSONL log, with <code>meta.parent</code> pointing at the orchestrator session;</li>82 <li>a full agent engine over that worktree with <strong>attenuated capabilities</strong>: permissions83 are non-interactive (every ask resolves to deny), scoped to the worktree — capability attenuation,84 a real security argument, not a convention.</li>85</ol>86<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/tasks</span></div>87<pre class="term" data-no-copy><code> <span class="t-b">tasks</span>88 <span class="t-ember">●</span> fix-auth-bug <span class="t-ember">◑ design</span> <span class="t-dim">$0.42</span> ⠹ edit…89 <span class="t-ok">✓</span> add-rate-limit <span class="t-ok">done</span> <span class="t-ok">+118</span> <span class="t-err">−24</span> · verify <span class="t-ok">✓</span>90 <span class="t-err">✗</span> flaky-retry <span class="t-err">failed</span> <span class="t-dim">verify ✗ — see child session</span></code></pre></div>9192<h2 id="lifecycle">Lifecycle<a class="anchor" href="#lifecycle">#</a></h2>93<table>94 <tr><th>Step</th><th>What happens</th></tr>95 <tr><td><code>/spawn</code></td><td class="wrap">Worktree + branch + child session created; a durable <code>subtask.created</code> event lands in the orchestrator log.</td></tr>96 <tr><td>run</td><td class="wrap">The child works with phase gates and the verify loop active — designs and checks happen inside the isolation too.</td></tr>97 <tr><td>finish</td><td class="wrap">Changes are committed onto the subtask branch; <code>subtask.completed</code> records the outcome, REAL git diff stats, and the verify verdict.</td></tr>98 <tr><td><code>/merge</code></td><td class="wrap">Supervised <code>git merge --no-ff</code> of the branch into your current branch. Conflicts abort cleanly, leaving the tree untouched.</td></tr>99</table>100101<h2 id="conflicts">Conflict resolution<a class="anchor" href="#conflicts">#</a></h2>102<p>When two subtask branches collide, the merge aborts and reports. The recommended move: ask103KHAELOR to resolve, giving it both designs — they are in the logs — as context. The orchestrator104can even <code>/spawn</code> a dedicated resolution subtask.</p>105106<h2 id="replay-sandbox">The same mechanics power /replay<a class="anchor" href="#replay-sandbox">#</a></h2>107<p><code>/replay</code> reuses the worktree machinery as a sandbox: the re-executed tool calls run108in a throwaway copy that is removed afterwards, branch and all. See109<a href="/docs/fork-replay.html">Fork · replay · sdiff</a>.</p>110111<h2 id="hygiene">Hygiene<a class="anchor" href="#hygiene">#</a></h2>112<ul>113 <li>Worktrees live under <code>.khaelor/worktrees/</code> — add it to <code>.gitignore</code> if you have not.</li>114 <li>Merged branches are deleted; failed ones are kept for inspection.</li>115 <li>The daemon's goal runs use the same mechanism (<code>khaelor/goal-<runId></code> branches).</li>116</ul>117118<div class="pager">119 <div><span class="label">Previous</span><a href="/docs/verification.html">← Verification</a></div>120 <div class="next"><span class="label">Next</span><a href="/docs/daemon.html">The daemon →</a></div>121</div>122123</article>124</div></main>125126<footer class="site-footer"><div class="inner">127 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>128 <span>Anthropic-powered · terminal-native by design</span>129</div></footer>130131</body>132</html>133