diff --git a/src/main/index.ts b/src/main/index.ts
index 69b367dc..4fb973ce 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -55,6 +55,7 @@ import { WorktreeWatcher } from './worktree-watcher'
 import { FileContentWatcher } from './file-content-watcher'
 import { SnoozeTimer } from './snooze-timer'
 import { getWeeklyStats } from './weekly-stats'
+import { discoverTools, runTool } from './tools'
 import type { TerminalTab, PaneNode, PaneLeaf } from '../shared/state/terminals'
 import { getLeaves, mapLeaves } from '../shared/state/terminals'
 import { listWorktrees, listBranches, continueWorktree, isWorktreeDirty, defaultWorktreeDir, getChangedFiles, getFileDiff, getBranchCommits, getCommitDiff, getCommitMeta, getCommitChangedFiles, getCommitFileDiffSides, getCommitRangeChangedFiles, getCommitRangeFileDiffSides, getMainWorktreeStatus, prepareMainForMerge, mergeWorktreeLocally, getBranchSha, previewMergeConflicts, getBranchDiffStats, listAllFiles, listRecentCommitShas, readWorktreeFile, readWorktreeFileBinary, writeWorktreeFile, getFileDiffSides, getCurrentBranch, renameWorktreeBranch, symlinkClaudeSettings, pruneWorktrees, type MergeStrategy } from './worktree'
@@ -1916,6 +1917,18 @@ function registerIpcHandlers(): void {
     return getBranchCommits(worktreePath)
   })
 
+  transport.onRequest('tools:list', async (_ctx, worktreePath: string) => {
+    return discoverTools(worktreePath)
+  })
+
+  transport.onRequest('tools:run', async (_ctx, worktreePath: string, toolId: string) => {
+    const wt = store.getSnapshot().state.worktrees.list.find((w) => w.path === worktreePath)
+    return runTool(worktreePath, toolId, {
+      branch: wt?.branch ?? '',
+      repoRoot: wt?.repoRoot ?? worktreePath
+    })
+  })
+
   transport.onRequest('worktree:commitDiff', async (_ctx, worktreePath: string, hash: string) => {
     return getCommitDiff(worktreePath, hash)
   })
diff --git a/src/main/repo-config.ts b/src/main/repo-config.ts
index c1a49db2..26a95a63 100644
--- a/src/main/repo-config.ts
+++ b/src/main/repo-config.ts
@@ -60,7 +60,7 @@ export function saveRepoConfig(repoRoot: string, next: RepoConfig): RepoConfig {
   if (next.mergeStrategy) cleaned.mergeStrategy = next.mergeStrategy
   // Migrate legacy hideMergePanel / hidePrPanel into hiddenRightPanels
   // on write. Only the new field is persisted going forward.
-  const hidden: Record<string, boolean> = { ...(next.hiddenRightPanels || {}) }
+  const hidden: Record<string, boolean | undefined> = { ...(next.hiddenRightPanels || {}) }
   if (next.hideMergePanel && hidden.merge === undefined) hidden.merge = true
   if (next.hidePrPanel && hidden.pr === undefined) hidden.pr = true
   // Compact: drop `false` entries that match the default visibility
diff --git a/src/main/tools.test.ts b/src/main/tools.test.ts
new file mode 100644
index 00000000..a5985685
--- /dev/null
+++ b/src/main/tools.test.ts
@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, chmodSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { discoverTools, runTool } from './tools'
+
+let root: string
+
+function addTool(id: string, manifest: unknown, script?: string): string {
+  const dir = join(root, '.ness/tools', id)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'tool.json'), JSON.stringify(manifest))
+  if (script !== undefined) {
+    const scriptPath = join(dir, 'run.sh')
+    writeFileSync(scriptPath, script)
+    chmodSync(scriptPath, 0o755)
+  }
+  return dir
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'ness-tools-'))
+})
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true })
+})
+
+const ctx = { branch: 'feature/x', repoRoot: '/repo' }
+
+describe('discoverTools', () => {
+  it('returns [] when there is no tools directory', () => {
+    expect(discoverTools(root)).toEqual([])
+  })
+
+  it('reads the manifest and defaults script + refresh', () => {
+    addTool('pr-comments', { title: 'PR Comments' })
+    const [spec] = discoverTools(root)
+    expect(spec.id).toBe('pr-comments')
+    expect(spec.title).toBe('PR Comments')
+    expect(spec.script).toBe('run.sh')
+    expect(spec.refresh).toBe('manual')
+  })
+
+  it('falls back to the directory name when title is missing', () => {
+    addTool('deploys', {})
+    expect(discoverTools(root)[0].title).toBe('deploys')
+  })
+
+  it('skips a directory whose manifest is malformed', () => {
+    const dir = join(root, '.ness/tools/broken')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'tool.json'), '{not json')
+    expect(discoverTools(root)).toEqual([])
+  })
+
+  it('rejects a script path that escapes the tool directory', () => {
+    addTool('evil', { title: 'Evil', script: '../../../../bin/sh' })
+    expect(discoverTools(root)).toEqual([])
+  })
+})
+
+describe('runTool', () => {
+  it('returns stdout as markdown', async () => {
+    addTool('hello', { title: 'Hello' }, '#!/bin/sh\necho "## Section"\necho "- a row"\n')
+    const res = await runTool(root, 'hello', ctx)
+    expect(res.ok).toBe(true)
+    expect(res.markdown).toContain('## Section')
+    expect(res.markdown).toContain('- a row')
+  })
+
+  it('exposes the ness env vars to the script', async () => {
+    addTool('env', { title: 'Env' }, '#!/bin/sh\necho "$NESS_BRANCH $NESS_TOOL_ID"\n')
+    const res = await runTool(root, 'env', ctx)
+    expect(res.markdown.trim()).toBe('feature/x env')
+  })
+
+  it('reports a non-zero exit but still surfaces any output', async () => {
+    addTool('fails', { title: 'Fails' }, '#!/bin/sh\necho "partial"\necho "boom" >&2\nexit 3\n')
+    const res = await runTool(root, 'fails', ctx)
+    expect(res.ok).toBe(false)
+    expect(res.markdown).toContain('partial')
+    expect(res.error).toContain('boom')
+  })
+
+  it('errors on an unknown tool id', async () => {
+    const res = await runTool(root, 'nope', ctx)
+    expect(res.ok).toBe(false)
+    expect(res.error).toContain('Unknown tool')
+  })
+
+  it('errors when the manifest points at a missing script', async () => {
+    addTool('noscript', { title: 'No Script' })
+    const res = await runTool(root, 'noscript', ctx)
+    expect(res.ok).toBe(false)
+    expect(res.error).toContain('Script not found')
+  })
+
+  it('tells the user to chmod +x when the script is not executable', async () => {
+    addTool('noexec', { title: 'No Exec' }, '#!/bin/sh\necho hi\n')
+    chmodSync(join(root, '.ness/tools/noexec/run.sh'), 0o644)
+    const res = await runTool(root, 'noexec', ctx)
+    expect(res.ok).toBe(false)
+    expect(res.error).toContain('chmod +x')
+  })
+})
diff --git a/src/main/tools.ts b/src/main/tools.ts
new file mode 100644
index 00000000..efbfdca6
--- /dev/null
+++ b/src/main/tools.ts
@@ -0,0 +1,161 @@
+import { spawn } from 'child_process'
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import { log } from './debug'
+import {
+  DEFAULT_TOOL_SCRIPT,
+  TOOL_MANIFEST_FILENAME,
+  TOOLS_DIRNAME,
+  type ToolRunResult,
+  type ToolSpec
+} from '../shared/tools'
+
+const RUN_TIMEOUT_MS = 20_000
+const MAX_OUTPUT_BYTES = 256 * 1024
+
+
+/** Tools live in the worktree, not the repo root, so a branch can iterate
+ * on its own tooling and a PR that edits a tool exercises the new version.
+ * (Note this differs from `.ness.json`, which resolves against repoRoot.) */
+function toolsDir(worktreePath: string): string {
+  return join(worktreePath, TOOLS_DIRNAME)
+}
+
+function parseManifest(dir: string, id: string): ToolSpec | null {
+  const manifestPath = join(dir, TOOL_MANIFEST_FILENAME)
+  if (!existsSync(manifestPath)) return null
+  try {
+    const raw = JSON.parse(readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>
+    const title = typeof raw.title === 'string' && raw.title.trim() ? raw.title.trim() : id
+    const script =
+      typeof raw.script === 'string' && raw.script.trim() ? raw.script.trim() : DEFAULT_TOOL_SCRIPT
+    // Keep the script inside its own tool directory — a manifest shouldn't
+    // be able to point at an arbitrary path elsewhere on disk.
+    if (script.startsWith('/') || script.split('/').includes('..')) {
+      log('tools', `tool ${id}: rejecting script path outside tool dir: ${script}`)
+      return null
+    }
+    return {
+      id,
+      title,
+      script,
+      dir,
+      refresh: raw.refresh === 'auto' ? 'auto' : 'manual'
+    }
+  } catch (err) {
+    log('tools', `tool ${id}: failed to parse manifest: ${(err as Error).message}`)
+    return null
+  }
+}
+
+export function discoverTools(worktreePath: string): ToolSpec[] {
+  if (!worktreePath) return []
+  const root = toolsDir(worktreePath)
+  if (!existsSync(root)) return []
+  let entries: string[]
+  try {
+    entries = readdirSync(root)
+  } catch (err) {
+    log('tools', `failed to read ${root}: ${(err as Error).message}`)
+    return []
+  }
+  const specs: ToolSpec[] = []
+  for (const id of entries.sort()) {
+    if (id.startsWith('.')) continue
+    const dir = join(root, id)
+    try {
+      if (!statSync(dir).isDirectory()) continue
+    } catch {
+      continue
+    }
+    const spec = parseManifest(dir, id)
+    if (spec) specs.push(spec)
+  }
+  return specs
+}
+
+export async function runTool(
+  worktreePath: string,
+  toolId: string,
+  ctx: { branch: string; repoRoot: string }
+): Promise<ToolRunResult> {
+  const spec = discoverTools(worktreePath).find((t) => t.id === toolId)
+  if (!spec) return { ok: false, markdown: '', error: `Unknown tool: ${toolId}` }
+  const scriptPath = join(spec.dir, spec.script)
+  if (!existsSync(scriptPath)) {
+    return { ok: false, markdown: '', error: `Script not found: ${spec.script}` }
+  }
+
+  return new Promise((resolve) => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    const finish = (result: ToolRunResult): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(result)
+    }
+
+    let child: ReturnType<typeof spawn> | null = null
+    const timer = setTimeout(() => {
+      child?.kill('SIGKILL')
+      finish({ ok: false, markdown: stdout, error: `Timed out after ${RUN_TIMEOUT_MS / 1000}s` })
+    }, RUN_TIMEOUT_MS)
+
+    try {
+      // Spawned directly rather than through a login shell: the script's
+      // own shebang decides the interpreter, and rc-file chatter (nvm
+      // banners, starship init) can't leak into stdout — which here IS
+      // the panel body. PATH is already the login-shell PATH thanks to
+      // path-fix.ts at boot, so there's nothing to gain from `-ilc`.
+      child = spawn(scriptPath, [], {
+        cwd: worktreePath,
+        env: {
+          ...process.env,
+          NESS_WORKTREE_PATH: worktreePath,
+          NESS_BRANCH: ctx.branch,
+          NESS_REPO_ROOT: ctx.repoRoot,
+          NESS_TOOL_DIR: spec.dir,
+          NESS_TOOL_ID: spec.id
+        }
+      })
+    } catch (err) {
+      finish({ ok: false, markdown: '', error: (err as Error).message })
+      return
+    }
+
+    child.stdout?.on('data', (d) => {
+      if (stdout.length < MAX_OUTPUT_BYTES) stdout += d.toString()
+    })
+    child.stderr?.on('data', (d) => {
+      if (stderr.length < MAX_OUTPUT_BYTES) stderr += d.toString()
+    })
+    child.on('error', (err) => {
+      const code = (err as NodeJS.ErrnoException).code
+      finish({
+        ok: false,
+        markdown: '',
+        error:
+          code === 'EACCES'
+            ? `${spec.script} is not executable — run chmod +x`
+            : err.message
+      })
+    })
+    child.on('close', (code) => {
+      const truncated = stdout.length >= MAX_OUTPUT_BYTES
+      const markdown = truncated ? stdout.slice(0, MAX_OUTPUT_BYTES) : stdout
+      if (code === 0) {
+        finish({ ok: true, markdown })
+        return
+      }
+      // A failing script that still printed something gets to render its
+      // own output — it may be formatting the error better than we can.
+      finish({
+        ok: false,
+        markdown,
+        error: stderr.trim().slice(0, 500) || `Exited with code ${code}`
+      })
+    })
+  })
+}
diff --git a/src/renderer/App.tsx b/src/renderer/App.tsx
index 0bd1c7be..e0766672 100644
--- a/src/renderer/App.tsx
+++ b/src/renderer/App.tsx
@@ -242,11 +242,18 @@ function DesktopApp(): JSX.Element {
   // Cleared alongside the repo when the modal closes.
   const [newWorktreeInitialPRNumber, setNewWorktreeInitialPRNumber] = useState<number | undefined>(undefined)
   const [newWorktreeForkSource, setNewWorktreeForkSource] = useState<ForkSource | undefined>(undefined)
+  // Set by "Build a custom tool" in the right column so the screen opens
+  // with a branch name and kickoff prompt already filled in. Same
+  // transient lifetime as the two above.
+  const [newWorktreePrefill, setNewWorktreePrefill] = useState<
+    { branch: string; prompt: string } | undefined
+  >(undefined)
   useEffect(() => {
     if (!showNewWorktree) {
       setNewWorktreeRepo(undefined)
       setNewWorktreeInitialPRNumber(undefined)
       setNewWorktreeForkSource(undefined)
+      setNewWorktreePrefill(undefined)
     }
   }, [showNewWorktree])
   // Chat's "Fork into new worktree" opens the create screen with the
@@ -1643,6 +1650,8 @@ const setQuestStep = useCallback((next: QuestStep) => {
             defaultRepoRoot={newWorktreeRepo ?? (activeWorktreeId ? worktreeRepoByPath[activeWorktreeId] : undefined)}
             initialPRNumber={newWorktreeInitialPRNumber}
             forkSource={newWorktreeForkSource}
+            initialBranch={newWorktreePrefill?.branch}
+            initialPrompt={newWorktreePrefill?.prompt}
           />
         )}
         {reportIssueState !== null && (
@@ -1784,6 +1793,10 @@ const setQuestStep = useCallback((next: QuestStep) => {
               if (activeWorktreeId) void backend.panesOpenReview(activeWorktreeId)
             }}
             onCollapse={() => setRightColumnHidden(true)}
+            onBuildCustomTool={(branch, prompt) => {
+              setNewWorktreePrefill({ branch, prompt })
+              setShowNewWorktree(true)
+            }}
           /></div></div>
         )}
         {!singleScreenMode && !showNewWorktree && !showActivity && !showCleanup && !showCommandCenter && reportIssueState === null && rightColumnHidden && (
diff --git a/src/renderer/build-backend.ts b/src/renderer/build-backend.ts
index f1344d44..9e0e6269 100644
--- a/src/renderer/build-backend.ts
+++ b/src/renderer/build-backend.ts
@@ -205,6 +205,8 @@ export function buildBackend(
       mode?: 'working' | 'branch'
     ) => req('worktree:fileDiffSides', worktreePath, filePath, staged, mode),
     getBranchCommits: (worktreePath: string) => req('worktree:branchCommits', worktreePath),
+    listTools: (worktreePath: string) => req('tools:list', worktreePath),
+    runTool: (worktreePath: string, toolId: string) => req('tools:run', worktreePath, toolId),
     getCommitDiff: (worktreePath: string, hash: string) =>
       req('worktree:commitDiff', worktreePath, hash),
     getCommitMeta: (worktreePath: string, hash: string) =>
diff --git a/src/renderer/components/CustomToolPanel.tsx b/src/renderer/components/CustomToolPanel.tsx
new file mode 100644
index 00000000..baacf22c
--- /dev/null
+++ b/src/renderer/components/CustomToolPanel.tsx
@@ -0,0 +1,99 @@
+import { useCallback } from 'react'
+import { RefreshCw, TriangleAlert } from 'lucide-react'
+import type { ToolRunResult, ToolSpec } from '../types'
+import { Tooltip } from './Tooltip'
+import { RightPanel } from './RightPanel'
+import { SidebarMarkdown, type NessLinkAction } from './SidebarMarkdown'
+import { useWatchedQuery } from '../hooks/useWatchedQuery'
+import { toolPanelKey } from '../../shared/state/repo-configs'
+import { useBackend } from '../backend'
+
+interface CustomToolPanelProps {
+  spec: ToolSpec
+  worktreePath: string | null
+  onSendToAgent?: (text: string) => void
+  onOpenFile?: (filePath: string) => void
+}
+
+export function CustomToolPanel({
+  spec,
+  worktreePath,
+  onSendToAgent,
+  onOpenFile
+}: CustomToolPanelProps): JSX.Element | null {
+  const backend = useBackend()
+  const fetcher = useCallback(
+    (path: string) => backend.runTool(path, spec.id),
+    [backend, spec.id]
+  )
+
+  const { data, loading, refresh } = useWatchedQuery<ToolRunResult>({
+    worktreePath,
+    cacheKey: `tool:${spec.id}`,
+    fetcher,
+    // A `manual` tool still runs on mount and on the refresh button, but
+    // never on a timer or a git change — tool scripts routinely hit the
+    // network, and the built-in panels' cadence would hammer an API.
+    fallbackPollMs: spec.refresh === 'auto' ? 30000 : 0,
+    revalidateOnFileChange: spec.refresh === 'auto'
+  })
+
+  const handleAction = useCallback(
+    (action: NessLinkAction) => {
+      if (action.verb === 'send') {
+        const text = action.params.get('text')
+        if (text) onSendToAgent?.(text)
+        return
+      }
+      if (action.verb === 'file') {
+        const path = action.params.get('path')
+        if (path) onOpenFile?.(path)
+        return
+      }
+      if (action.verb === 'refresh') refresh()
+    },
+    [onSendToAgent, onOpenFile, refresh]
+  )
+
+  if (!worktreePath) return null
+
+  const actions = (
+    <>
+      {data && !data.ok && (
+        <Tooltip label={data.error || 'Tool failed'}>
+          <TriangleAlert className="icon-xs text-warning" />
+        </Tooltip>
+      )}
+      <Tooltip label="Refresh">
+        <button
+          onClick={(e) => {
+            e.stopPropagation()
+            refresh()
+          }}
+          className="text-faint hover:text-fg transition-colors cursor-pointer"
+        >
+          <RefreshCw className={`icon-xs ${loading ? 'animate-spin' : ''}`} />
+        </button>
+      </Tooltip>
+    </>
+  )
+
+  const body = data?.markdown?.trim()
+
+  return (
+    <RightPanel id={toolPanelKey(spec.id)} title={spec.title} actions={actions} maxHeight="max-h-56">
+      <div className="flex-1 overflow-y-auto min-h-0 text-xs">
+        {!data && loading && <div className="px-3 py-2 text-xs text-faint">Running…</div>}
+        {body ? (
+          <SidebarMarkdown markdown={body} onAction={handleAction} />
+        ) : (
+          data && (
+            <div className="px-3 py-2 text-xs text-faint italic">
+              {data.ok ? 'No output' : data.error || 'Tool failed'}
+            </div>
+          )
+        )}
+      </div>
+    </RightPanel>
+  )
+}
diff --git a/src/renderer/components/NewWorktreeScreen.tsx b/src/renderer/components/NewWorktreeScreen.tsx
index 084551ae..f3edb40f 100644
--- a/src/renderer/components/NewWorktreeScreen.tsx
+++ b/src/renderer/components/NewWorktreeScreen.tsx
@@ -57,6 +57,11 @@ interface NewWorktreeScreenProps {
   /** When set, the new worktree's first agent tab resumes a copy of this
    *  conversation instead of starting empty. */
   forkSource?: ForkSource
+  /** Pre-fill the branch name and kickoff prompt, for entry points that
+   * already know the task (e.g. "Build a custom tool"). Both stay
+   * editable — the point is to show the user what's about to run. */
+  initialBranch?: string
+  initialPrompt?: string
 }
 
 /** Sort + clean the local-branch list from the backend. The backend already
@@ -123,12 +128,12 @@ const STARTER_PROMPTS = [
 const KBD_CHIP = 'text-xs text-faint bg-bg px-1.5 py-0.5 rounded border border-border font-mono'
 const KBD_CHIP_ON_ACCENT = 'text-xs text-white bg-white/20 px-1.5 py-0.5 rounded border border-white/30 font-mono'
 
-export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, defaultRepoRoot, initialPRNumber, forkSource }: NewWorktreeScreenProps): JSX.Element {
+export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, defaultRepoRoot, initialPRNumber, forkSource, initialBranch, initialPrompt }: NewWorktreeScreenProps): JSX.Element {
   const [mode, setMode] = useState<'fresh' | 'teleport' | 'pr'>(initialPRNumber ? 'pr' : 'fresh')
   const [selectedRepo, setSelectedRepo] = useState<string>(
     defaultRepoRoot && repoRoots.includes(defaultRepoRoot) ? defaultRepoRoot : repoRoots[0] || ''
   )
-  const [branch, setBranch] = useState('')
+  const [branch, setBranch] = useState(initialBranch ?? '')
   const [existingBranch, setExistingBranch] = useState<string | null>(null)
   // Free-text ref: commit SHA, tag, remote-tracking ref (`origin/foo`), etc.
   // Used as the base the new branch (`refBranch`) is forked from — the
@@ -138,7 +143,7 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
   // The name of the new branch to create at `refValue` on the Ref tab.
   const [refBranch, setRefBranch] = useState('')
   const [branchTab, setBranchTab] = useState<'new' | 'existing' | 'ref'>('new')
-  const [prompt, setPrompt] = useState('')
+  const [prompt, setPrompt] = useState(initialPrompt ?? '')
   const settings = useSettings()
   const [reviewPrompt, setReviewPrompt] = useState(settings.prReviewPrompt)
   const [teleportInput, setTeleportInput] = useState('')
diff --git a/src/renderer/components/RightColumn.tsx b/src/renderer/components/RightColumn.tsx
index 92579add..99b7bfb4 100644
--- a/src/renderer/components/RightColumn.tsx
+++ b/src/renderer/components/RightColumn.tsx
@@ -1,10 +1,16 @@
-import type { PRStatus, Worktree, RepoConfig } from '../types'
+import { useCallback, useMemo } from 'react'
+import type { PRStatus, Worktree, RepoConfig, ToolSpec } from '../types'
 import {
   effectiveHiddenRightPanels,
   effectiveRightPanelOrder,
+  isCustomToolPanelKey,
+  toolPanelKey,
   type HiddenRightPanels,
   type RightPanelKey
 } from '../../shared/state/repo-configs'
+import { BUILD_CUSTOM_TOOL_BRANCH, BUILD_CUSTOM_TOOL_PROMPT } from '../../shared/tools'
+import { useWatchedQuery } from '../hooks/useWatchedQuery'
+import { CustomToolPanel } from './CustomToolPanel'
 import { PRStatusPanel, MergeLocallyPanel } from './PRStatusPanel'
 import { BranchCommitsPanel } from './BranchCommitsPanel'
 import { ChangedFilesPanel } from './ChangedFilesPanel'
@@ -42,6 +48,9 @@ interface RightColumnProps {
   onOpenPR: (url: string) => void
   onOpenReview: () => void
   onCollapse: () => void
+  /** Opens the new-worktree screen pre-filled with a branch name and the
+   * custom-tool authoring contract as the kickoff prompt. */
+  onBuildCustomTool: (branch: string, prompt: string) => void
 }
 
 export function RightColumn({
@@ -63,11 +72,29 @@ export function RightColumn({
   onSendToAgent,
   onOpenPR,
   onOpenReview,
-  onCollapse
+  onCollapse,
+  onBuildCustomTool
 }: RightColumnProps): JSX.Element {
   const backend = useBackend()
+
+  const toolsFetcher = useCallback(
+    (path: string) => backend.listTools(path),
+    [backend]
+  )
+  const { data: toolsData } = useWatchedQuery<ToolSpec[]>({
+    worktreePath: activeWorktreeId,
+    cacheKey: 'tools',
+    fetcher: toolsFetcher
+  })
+  const tools = useMemo(() => toolsData ?? [], [toolsData])
+  const toolKeys = useMemo(() => tools.map((t) => toolPanelKey(t.id)), [tools])
+  const toolLabels = useMemo(
+    () => Object.fromEntries(tools.map((t) => [toolPanelKey(t.id), t.title])),
+    [tools]
+  )
+
   const hidden = effectiveHiddenRightPanels(activeRepoConfig)
-  const order = effectiveRightPanelOrder(activeRepoConfig)
+  const order = effectiveRightPanelOrder(activeRepoConfig, toolKeys)
 
   const handleChangeHidden = (next: HiddenRightPanels): void => {
     if (!activeRepoRoot) return
@@ -89,6 +116,21 @@ export function RightColumn({
 
   const renderPanel = (key: RightPanelKey): JSX.Element | null => {
     if (hidden[key]) return null
+    if (isCustomToolPanelKey(key)) {
+      const spec = tools.find((t) => toolPanelKey(t.id) === key)
+      if (!spec) return null
+      return (
+        <CustomToolPanel
+          key={key}
+          spec={spec}
+          worktreePath={activeWorktreeId}
+          onSendToAgent={
+            activeWorktreeId ? (text) => onSendToAgent(activeWorktreeId, text) : undefined
+          }
+          onOpenFile={onOpenFile}
+        />
+      )
+    }
     switch (key) {
       case 'merge':
         return (
@@ -159,9 +201,13 @@ export function RightColumn({
       <RightColumnToolbar
         hidden={hidden}
         order={order}
+        customLabels={toolLabels}
         onChangeHidden={handleChangeHidden}
         onChangeOrder={handleChangeOrder}
         onCollapse={onCollapse}
+        onBuildCustomTool={() =>
+          onBuildCustomTool(BUILD_CUSTOM_TOOL_BRANCH, BUILD_CUSTOM_TOOL_PROMPT)
+        }
         canConfigure={!!activeRepoRoot}
       />
       {order.map((key) => renderPanel(key))}
diff --git a/src/renderer/components/RightColumnToolbar.tsx b/src/renderer/components/RightColumnToolbar.tsx
index 04127b3a..0c7b4958 100644
--- a/src/renderer/components/RightColumnToolbar.tsx
+++ b/src/renderer/components/RightColumnToolbar.tsx
@@ -1,9 +1,13 @@
 import { useState, useRef, useEffect } from 'react'
-import { PanelRightClose, SlidersHorizontal, Check, ChevronUp, ChevronDown } from 'lucide-react'
+import { PanelRightClose, SlidersHorizontal, Check, ChevronUp, ChevronDown, Wrench } from 'lucide-react'
 import { Tooltip } from './Tooltip'
-import type { HiddenRightPanels, RightPanelKey } from '../../shared/state/repo-configs'
+import type {
+  BuiltinRightPanelKey,
+  HiddenRightPanels,
+  RightPanelKey
+} from '../../shared/state/repo-configs'
 
-const LABELS: Record<RightPanelKey, string> = {
+const LABELS: Record<BuiltinRightPanelKey, string> = {
   merge: 'Merge Locally',
   pr: 'PR Status',
   todos: 'Todos',
@@ -18,12 +22,17 @@ const LABELS: Record<RightPanelKey, string> = {
 interface RightColumnToolbarProps {
   hidden: HiddenRightPanels
   order: RightPanelKey[]
+  /** Titles for discovered custom tools, keyed by their `tool:<id>` key. */
+  customLabels: Record<string, string>
   /** Called when the user toggles a panel. Receives the full next map. */
   onChangeHidden: (next: HiddenRightPanels) => void
   /** Called when the user reorders panels. Receives the full next order. */
   onChangeOrder: (next: RightPanelKey[]) => void
   /** Called when the user clicks the collapse button. */
   onCollapse: () => void
+  /** Opens the new-worktree screen pre-filled with the custom-tool
+   * authoring contract. */
+  onBuildCustomTool: () => void
   /** Whether per-repo dropdown is actionable (needs an active repo). */
   canConfigure: boolean
 }
@@ -31,11 +40,15 @@ interface RightColumnToolbarProps {
 export function RightColumnToolbar({
   hidden,
   order,
+  customLabels,
   onChangeHidden,
   onChangeOrder,
   onCollapse,
+  onBuildCustomTool,
   canConfigure
 }: RightColumnToolbarProps): JSX.Element {
+  const labelFor = (key: RightPanelKey): string =>
+    LABELS[key as BuiltinRightPanelKey] ?? customLabels[key] ?? key
   const [menuOpen, setMenuOpen] = useState(false)
   const menuRef = useRef<HTMLDivElement | null>(null)
 
@@ -114,13 +127,13 @@ export function RightColumnToolbar({
                     <span className="w-3 h-3 flex items-center justify-center shrink-0">
                       {visible && <Check className="icon-xs text-accent" />}
                     </span>
-                    <span className="flex-1">{LABELS[key]}</span>
+                    <span className="flex-1">{labelFor(key)}</span>
                   </button>
                   <button
                     onClick={() => movePanel(index, -1)}
                     disabled={isFirst}
                     className="flex items-center justify-center w-5 h-5 rounded text-muted hover:bg-panel/80 hover:text-fg-bright disabled:opacity-30 disabled:cursor-not-allowed cursor-pointer"
-                    aria-label={`Move ${LABELS[key]} up`}
+                    aria-label={`Move ${labelFor(key)} up`}
                   >
                     <ChevronUp className="icon-xs" />
                   </button>
@@ -128,13 +141,28 @@ export function RightColumnToolbar({
                     onClick={() => movePanel(index, 1)}
                     disabled={isLast}
                     className="flex items-center justify-center w-5 h-5 rounded text-muted hover:bg-panel/80 hover:text-fg-bright disabled:opacity-30 disabled:cursor-not-allowed cursor-pointer"
-                    aria-label={`Move ${LABELS[key]} down`}
+                    aria-label={`Move ${labelFor(key)} down`}
                   >
                     <ChevronDown className="icon-xs" />
                   </button>
                 </div>
               )
             })}
+            <div className="border-t border-border my-1" />
+            <button
+              onClick={() => {
+                setMenuOpen(false)
+                onBuildCustomTool()
+              }}
+              className="w-full flex items-start gap-2 px-3 py-1.5 hover:bg-panel/60 cursor-pointer text-left"
+              role="menuitem"
+            >
+              <Wrench className="icon-xs text-dim shrink-0 mt-0.5" />
+              <span className="min-w-0">
+                <span className="block text-xs text-fg-bright">Build a custom tool…</span>
+                <span className="block text-xs text-faint">Opens a new worktree</span>
+              </span>
+            </button>
           </div>
         )}
         </div>
diff --git a/src/renderer/components/SidebarMarkdown.tsx b/src/renderer/components/SidebarMarkdown.tsx
new file mode 100644
index 00000000..48273f4d
--- /dev/null
+++ b/src/renderer/components/SidebarMarkdown.tsx
@@ -0,0 +1,145 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import ReactMarkdown, { defaultUrlTransform, type Components } from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+import { useBackend } from '../backend'
+
+/** Markdown rendered into a ~280px right-column panel. The component map
+ * deliberately re-uses the built-in panels' vocabulary rather than
+ * document typography: headings become the section headers from
+ * ChangedFilesPanel, list items become rows. A tool script can only
+ * express what this map can render, which is what keeps custom panels
+ * from drifting out of the design system.
+ *
+ * No rehype-raw — raw HTML in tool output stays inert. */
+
+export interface NessLinkAction {
+  /** e.g. `send`, `file` — the part after `ness:`. */
+  verb: string
+  params: URLSearchParams
+}
+
+const REMARK_PLUGINS = [remarkGfm]
+
+/** react-markdown blanks any href whose protocol isn't http/https/mailto/
+ * etc., so `ness:` action links arrive as `href=""` and fall through to
+ * the inert-text branch below. Let ours through and keep the default
+ * sanitizer for everything else — it's what stops `javascript:`. */
+function urlTransform(url: string): string {
+  return url.startsWith('ness:') ? url : defaultUrlTransform(url)
+}
+
+/** Set inside <li> so paragraphs don't add a second layer of row padding
+ * when the markdown uses a loose list. */
+const InRowContext = createContext(false)
+
+const ROW_CLASS =
+  'flex items-center gap-2 px-3 py-1 text-xs text-fg hover:bg-panel-raised cursor-default group'
+const SECTION_CLASS =
+  'px-3 py-1.5 text-xs font-medium text-dim uppercase tracking-wider bg-panel-raised/50'
+
+function Paragraph({ children }: { children?: ReactNode }): JSX.Element {
+  const inRow = useContext(InRowContext)
+  if (inRow) return <>{children}</>
+  return <div className="px-3 py-1 text-xs text-fg">{children}</div>
+}
+
+interface SidebarMarkdownProps {
+  markdown: string
+  onAction?: (action: NessLinkAction) => void
+}
+
+export function SidebarMarkdown({ markdown, onAction }: SidebarMarkdownProps): JSX.Element {
+  const backend = useBackend()
+
+  const components = useMemo<Components>(() => {
+    const Section = ({ children }: { children?: ReactNode }): JSX.Element => (
+      <div className={SECTION_CLASS}>{children}</div>
+    )
+    return {
+      h1: Section,
+      h2: Section,
+      h3: ({ children }) => (
+        <div className="px-3 py-1 text-xs font-medium text-dim uppercase tracking-wider">
+          {children}
+        </div>
+      ),
+      h4: ({ children }) => (
+        <div className="px-3 py-1 text-xs font-medium text-muted">{children}</div>
+      ),
+      p: Paragraph,
+      // No wrapper padding: rows sit flush under their section header,
+      // the way ChangedFilesPanel's do.
+      ul: ({ children }) => <>{children}</>,
+      ol: ({ children }) => <>{children}</>,
+      li: ({ children }) => (
+        <InRowContext.Provider value={true}>
+          <div className={ROW_CLASS}>
+            <span className="truncate min-w-0 flex-1">{children}</span>
+          </div>
+        </InRowContext.Provider>
+      ),
+      a: ({ href, children }) => {
+        const target = href ?? ''
+        if (target.startsWith('ness:')) {
+          return (
+            <button
+              onClick={() => {
+                const rest = target.slice('ness:'.length)
+                const [verb, query = ''] = rest.split('?')
+                onAction?.({ verb, params: new URLSearchParams(query) })
+              }}
+              className="text-accent hover:underline cursor-pointer"
+            >
+              {children}
+            </button>
+          )
+        }
+        if (!/^https?:/i.test(target)) return <span className="text-fg">{children}</span>
+        return (
+          <button
+            onClick={() => backend.openExternal(target)}
+            className="text-accent hover:underline cursor-pointer"
+          >
+            {children}
+          </button>
+        )
+      },
+      code: ({ children }) => (
+        <code className="font-mono text-xs text-muted tabular-nums">{children}</code>
+      ),
+      pre: ({ children }) => (
+        <pre className="mx-3 my-1 p-2 rounded bg-surface text-xs font-mono overflow-x-auto">
+          {children}
+        </pre>
+      ),
+      strong: ({ children }) => <span className="text-fg-bright font-medium">{children}</span>,
+      em: ({ children }) => <span className="text-faint italic">{children}</span>,
+      blockquote: ({ children }) => (
+        <div className="px-3 py-1 border-l-2 border-border ml-3 text-xs text-faint">{children}</div>
+      ),
+      hr: () => <div className="border-b border-border my-1" />,
+      table: ({ children }) => (
+        <div className="px-3 py-1 overflow-x-auto">
+          <table className="text-xs">{children}</table>
+        </div>
+      ),
+      th: ({ children }) => (
+        <th className="text-left pr-3 font-medium text-dim uppercase tracking-wider">{children}</th>
+      ),
+      td: ({ children }) => <td className="pr-3 align-top">{children}</td>,
+      // A 280px column is not a place for images, and rendering them
+      // would let tool output phone home on render.
+      img: () => null
+    }
+  }, [backend, onAction])
+
+  return (
+    <ReactMarkdown
+      remarkPlugins={REMARK_PLUGINS}
+      urlTransform={urlTransform}
+      components={components}
+    >
+      {markdown}
+    </ReactMarkdown>
+  )
+}
diff --git a/src/renderer/hooks/useWatchedQuery.ts b/src/renderer/hooks/useWatchedQuery.ts
index 5808ae8e..dca6b33f 100644
--- a/src/renderer/hooks/useWatchedQuery.ts
+++ b/src/renderer/hooks/useWatchedQuery.ts
@@ -48,7 +48,12 @@ export interface UseWatchedQueryOptions<T> {
    *  must not be served by an in-flight request that started before the
    *  change. Fetchers that dedup should honour it. */
   fetcher: (path: string, opts: { force: boolean }) => Promise<T>
+  /** 0 disables background polling — the query then only runs on mount,
+   * on worktree switch, and on an explicit refresh(). */
   fallbackPollMs?: number
+  /** When false, a git change in the worktree doesn't trigger a refetch.
+   * Needed for queries whose fetcher is expensive or hits the network. */
+  revalidateOnFileChange?: boolean
 }
 
 export interface UseWatchedQueryResult<T> {
@@ -60,7 +65,13 @@ export interface UseWatchedQueryResult<T> {
 export function useWatchedQuery<T>(
   opts: UseWatchedQueryOptions<T>
 ): UseWatchedQueryResult<T> {
-  const { worktreePath, cacheKey, fetcher, fallbackPollMs = 30000 } = opts
+  const {
+    worktreePath,
+    cacheKey,
+    fetcher,
+    fallbackPollMs = 30000,
+    revalidateOnFileChange = true
+  } = opts
   const backend = useBackend()
 
   const [data, setData] = useState<T | null>(() =>
@@ -118,19 +129,24 @@ export function useWatchedQuery<T>(
 
   useEffect(() => {
     if (!worktreePath) return
+    const interval = fallbackPollMs > 0 ? setInterval(() => refresh(), fallbackPollMs) : null
+    if (!revalidateOnFileChange) {
+      return () => {
+        if (interval) clearInterval(interval)
+      }
+    }
     backend.watchChangedFiles(worktreePath)
     const offInvalidated = backend.onChangedFilesInvalidated((path) => {
       if (path !== worktreePath) return
       cacheDelete(cacheKey, worktreePath)
       refresh({ force: true })
     })
-    const interval = setInterval(() => refresh(), fallbackPollMs)
     return () => {
-      clearInterval(interval)
+      if (interval) clearInterval(interval)
       offInvalidated()
       backend.unwatchChangedFiles(worktreePath)
     }
-  }, [worktreePath, cacheKey, refresh, fallbackPollMs, backend])
+  }, [worktreePath, cacheKey, refresh, fallbackPollMs, revalidateOnFileChange, backend])
 
   return { data, loading, refresh }
 }
diff --git a/src/renderer/types.ts b/src/renderer/types.ts
index f88d117a..e86ab9c8 100644
--- a/src/renderer/types.ts
+++ b/src/renderer/types.ts
@@ -7,6 +7,9 @@ export type { Worktree, PendingWorktree, PendingDeletion, ForkSource }
 import type { RepoConfig } from '../shared/state/repo-configs'
 export type { RepoConfig }
 
+import type { ToolSpec, ToolRunResult } from '../shared/tools'
+export type { ToolSpec, ToolRunResult }
+
 import type { WeeklyStats, TopWorktree } from '../shared/weekly-stats'
 export type { WeeklyStats, TopWorktree }
 
@@ -302,6 +305,8 @@ export interface ElectronAPI {
 
   getWeeklyStats(): Promise<WeeklyStats>
   getBranchCommits(worktreePath: string): Promise<BranchCommit[]>
+  listTools(worktreePath: string): Promise<ToolSpec[]>
+  runTool(worktreePath: string, toolId: string): Promise<ToolRunResult>
   getCommitDiff(worktreePath: string, hash: string): Promise<CommitDiff | null>
   getCommitMeta(worktreePath: string, hash: string): Promise<CommitMeta | null>
   getCommitChangedFiles(worktreePath: string, hash: string): Promise<ChangedFile[]>
diff --git a/src/shared/state/repo-configs.test.ts b/src/shared/state/repo-configs.test.ts
index 2751238d..a46277d8 100644
--- a/src/shared/state/repo-configs.test.ts
+++ b/src/shared/state/repo-configs.test.ts
@@ -174,6 +174,32 @@ describe('repoConfigsReducer', () => {
     expect(result).toHaveLength(DEFAULT_RIGHT_PANEL_ORDER.length)
   })
 
+  it('effectiveRightPanelOrder appends newly discovered tools at the end', () => {
+    const result = effectiveRightPanelOrder({ rightPanelOrder: ['pr'] as never }, [
+      'tool:pr-comments'
+    ])
+    expect(result[0]).toBe('pr')
+    expect(result[result.length - 1]).toBe('tool:pr-comments')
+    expect(result).toHaveLength(DEFAULT_RIGHT_PANEL_ORDER.length + 1)
+  })
+
+  it('effectiveRightPanelOrder honors a saved position for a custom tool', () => {
+    const result = effectiveRightPanelOrder(
+      { rightPanelOrder: ['tool:pr-comments', 'pr'] as never },
+      ['tool:pr-comments']
+    )
+    expect(result[0]).toBe('tool:pr-comments')
+    expect(result[1]).toBe('pr')
+  })
+
+  it('effectiveRightPanelOrder drops a saved tool that no longer exists', () => {
+    const result = effectiveRightPanelOrder({
+      rightPanelOrder: ['tool:deleted', 'pr'] as never
+    })
+    expect(result).not.toContain('tool:deleted')
+    expect(result).toHaveLength(DEFAULT_RIGHT_PANEL_ORDER.length)
+  })
+
   it('effectiveHiddenRightPanels handles null/empty config', () => {
     expect(effectiveHiddenRightPanels(null)).toEqual({ scratchpad: true })
     expect(effectiveHiddenRightPanels(undefined)).toEqual({ scratchpad: true })
diff --git a/src/shared/state/repo-configs.ts b/src/shared/state/repo-configs.ts
index 20defefe..aeef1494 100644
--- a/src/shared/state/repo-configs.ts
+++ b/src/shared/state/repo-configs.ts
@@ -1,4 +1,4 @@
-export type RightPanelKey =
+export type BuiltinRightPanelKey =
   | 'merge'
   | 'pr'
   | 'todos'
@@ -9,7 +9,21 @@ export type RightPanelKey =
   | 'context'
   | 'scratchpad'
 
-export const DEFAULT_RIGHT_PANEL_ORDER: RightPanelKey[] = [
+/** Custom tools discovered from `.harness/tools/<id>/` are namespaced so
+ * they can never collide with a builtin key. */
+export type CustomToolPanelKey = `tool:${string}`
+
+export type RightPanelKey = BuiltinRightPanelKey | CustomToolPanelKey
+
+export function isCustomToolPanelKey(key: string): key is CustomToolPanelKey {
+  return key.startsWith('tool:')
+}
+
+export function toolPanelKey(toolId: string): CustomToolPanelKey {
+  return `tool:${toolId}`
+}
+
+export const DEFAULT_RIGHT_PANEL_ORDER: BuiltinRightPanelKey[] = [
   'merge',
   'pr',
   'commits',
@@ -49,12 +63,20 @@ export interface RepoConfig {
 
 /** Read an effective panel order, filling in any keys missing from the
  * saved order with the canonical default order (appended at the end)
- * and dropping any unknown keys. Always returns all six keys exactly
- * once. */
-export function effectiveRightPanelOrder(config: RepoConfig | null | undefined): RightPanelKey[] {
+ * and dropping any unknown keys. Always returns every builtin key plus
+ * every currently-discovered custom tool key exactly once.
+ *
+ * `customKeys` comes from tool discovery, so a saved order referencing a
+ * tool that has since been deleted drops out naturally, and a newly
+ * added tool appears at the end without needing a config write. */
+export function effectiveRightPanelOrder(
+  config: RepoConfig | null | undefined,
+  customKeys: readonly RightPanelKey[] = []
+): RightPanelKey[] {
+  const canonical: RightPanelKey[] = [...DEFAULT_RIGHT_PANEL_ORDER, ...customKeys]
   const saved = config?.rightPanelOrder
-  if (!saved || saved.length === 0) return [...DEFAULT_RIGHT_PANEL_ORDER]
-  const known = new Set<RightPanelKey>(DEFAULT_RIGHT_PANEL_ORDER)
+  if (!saved || saved.length === 0) return canonical
+  const known = new Set<RightPanelKey>(canonical)
   const seen = new Set<RightPanelKey>()
   const out: RightPanelKey[] = []
   for (const k of saved) {
@@ -63,7 +85,7 @@ export function effectiveRightPanelOrder(config: RepoConfig | null | undefined):
       seen.add(k)
     }
   }
-  for (const k of DEFAULT_RIGHT_PANEL_ORDER) {
+  for (const k of canonical) {
     if (!seen.has(k)) out.push(k)
   }
   return out
diff --git a/src/shared/tools.ts b/src/shared/tools.ts
new file mode 100644
index 00000000..061e8135
--- /dev/null
+++ b/src/shared/tools.ts
@@ -0,0 +1,99 @@
+/** A user-defined right-column tool, discovered from
+ * `<worktree>/.ness/tools/<id>/tool.json`. The directory name is the
+ * id; the manifest supplies presentation. Nothing about how the panel
+ * looks comes from the script's output — the script only emits markdown
+ * for the body. */
+export interface ToolSpec {
+  /** Directory name under `.ness/tools/`. */
+  id: string
+  /** Panel header text. Static so the panel has a title before the
+   * script has ever run (and while it's failing). */
+  title: string
+  /** Script path relative to the tool directory. Defaults to `run.sh`. */
+  script: string
+  /** Absolute path to the tool directory, exported to the script as
+   * NESS_TOOL_DIR. */
+  dir: string
+  /** `auto` re-runs on the changed-files watcher signal and the poll
+   * interval; `manual` only runs on mount and on the refresh button. */
+  refresh: 'auto' | 'manual'
+}
+
+export interface ToolRunResult {
+  ok: boolean
+  /** Script stdout. Rendered as markdown regardless of ok, so a script
+   * can format its own error output. */
+  markdown: string
+  /** Set when the tool failed to run at all (spawn error, timeout,
+   * non-zero exit with no stdout). */
+  error?: string
+}
+
+export const TOOLS_DIRNAME = '.ness/tools'
+export const TOOL_MANIFEST_FILENAME = 'tool.json'
+export const DEFAULT_TOOL_SCRIPT = 'run.sh'
+
+/** Branch pre-filled alongside BUILD_CUSTOM_TOOL_PROMPT. */
+export const BUILD_CUSTOM_TOOL_BRANCH = 'custom-tool'
+
+/** Sent to the agent when the user clicks "Build a custom tool" in the
+ * right column's panel menu. It lives next to the types it describes so
+ * the contract has one source of truth — if the manifest fields, the env
+ * vars, or the markdown mapping change, this changes with them. */
+export const BUILD_CUSTOM_TOOL_PROMPT = `I want to add a custom Ness tool: a panel in this worktree's right column, backed by a script you write. Ask me what it should show if that isn't already clear from our conversation, then build it.
+
+## Layout
+
+Everything lives in this worktree:
+
+    .ness/tools/<id>/
+      tool.json
+      run.sh          # must be executable
+
+The directory name is the tool id. \`tool.json\`:
+
+    { "title": "PR Comments", "script": "run.sh", "refresh": "manual" }
+
+- **title** — the panel header. Static; it is never read from the script's output, so the panel has a title even while the script is failing.
+- **script** — path relative to the tool directory, defaults to \`run.sh\`. It must stay inside the tool directory.
+- **refresh** — \`"auto"\` re-runs on every git change in the worktree plus a 30s poll. \`"manual"\` (the default) runs only on mount and when the user clicks the panel's refresh button. Use \`manual\` for anything that hits the network or costs money.
+
+## The script
+
+- Spawned directly, so it needs a shebang — \`#!/usr/bin/env bash\`, python, node, whatever is executable.
+- cwd is the worktree root.
+- Env available: \`NESS_WORKTREE_PATH\`, \`NESS_BRANCH\`, \`NESS_REPO_ROOT\`, \`NESS_TOOL_DIR\`, \`NESS_TOOL_ID\`.
+- **stdout is markdown and becomes the entire panel body.** Don't print anything you don't want rendered.
+- stderr surfaces as an error tooltip on a non-zero exit. A script that fails but still wrote to stdout gets that output rendered anyway, so you can format your own error rows.
+- Killed after 20s. Output capped at 256KB.
+
+## Markdown vocabulary
+
+The panel is a ~280px column, not a document. Markdown is mapped onto the same vocabulary the built-in panels use, so only these carry meaning:
+
+- \`#\` / \`##\` → a section header bar (like "Changed Files")
+- \`###\` / \`####\` → a lighter subheading
+- \`- item\` → one panel row. Rows truncate, so keep them short.
+- backtick code → a monospace chip; good for counts, sizes, shas
+- \`**bold**\` → brightened, \`*italic*\` → dimmed
+- \`>\` → an indented note, \`---\` → a divider
+- tables render but are cramped; prefer rows
+
+Images and raw HTML are dropped. Prose paragraphs look wrong here — think rows, not documents.
+
+## Actions
+
+Links are how a row does something:
+
+- \`[Fix these](ness:send?text=Fix+the+failing+tests)\` — sends that text to the agent in this worktree
+- \`[src/app.ts](ness:file?path=src/app.ts)\` — opens the file
+- \`[Reload](ness:refresh)\` — re-runs the tool
+- \`[View PR](https://github.com/owner/repo/pull/1)\` — opens in the browser
+
+Query values must be URL-encoded. Any other link renders as inert text.
+
+## Finishing
+
+\`chmod +x\` the script, run it once yourself, and check the output reads as a tight list of rows rather than a wall of text. Then tell me to look — the panel shows up in this worktree's right column alongside the built-in ones, and can be reordered or hidden from the sliders menu at the top of that column. If it doesn't appear, the manifest failed to parse or the script isn't executable.
+
+Tools are discovered per worktree, so the panel is live here on this branch while we iterate. Commit it when it's right, and it reaches everyone else on merge.`