Runcastle

Docs From Codebase

MIT↓ 0 downloads

by runcastle

v1.0.1
v1.0.1v1.0.0

A single Claude Code agent reads your repository — a shell-expanded file map seeds it, and it can install and run the project — then writes and incrementally commits a real `docs/` set: a getting-started guide, an architecture overview, and per-module reference pages.

#documentation#content#single-agent#loop#docker

Topology

Disclosures

Disclosures — declared side-effect surface

Everything below runs on your machine or inside the sandbox when you use this workflow. Mismatches between these declarations and the actual code block publishing.

Host hooks

Commands executed on YOUR host machine by Sandcastle lifecycle hooks.

None declared.

Sandbox hooks

Commands executed inside the sandbox container.

  • npm install

Network access

None. The agent reads and writes only the local repository inside the sandbox; the sandbox hook runs `npm install` against your declared package registry.

Shell expansion

Prompt files contain !`command` blocks — the agent CLI executes these commands at prompt-load time. They are highlighted amber in the prompt files below.

Files

Diff vs the stock Sandcastle 0.12.0 template Dockerfile — green lines were added by the author, red lines were removed from stock.

+# Sandbox image for the Docs From Codebase workflow.
+# Node 22 + git + the Claude Code CLI, running as a non-root `agent` user.
+# Add your project's toolchain (python, go, ...) here if the agent needs to run
+# it to understand the project.
 FROM node:22-bookworm
  
-# System dependencies.
 RUN apt-get update && apt-get install -y --no-install-recommends \
       git \
       curl \
       jq \
       ca-certificates \
  && rm -rf /var/lib/apt/lists/*
  
 # Claude Code CLI (the agent runtime).
 RUN npm install -g @anthropic-ai/claude-code
  
 # Non-root agent user. `sandcastle docker build-image` aligns AGENT_UID/GID to
 # the host user via --build-arg to avoid permission errors on bind mounts.
+# node:22-bookworm already ships a "node" user at UID/GID 1000, so we RENAME it
+# (the stock Sandcastle template pattern) — groupadd/useradd would collide with
+# the existing IDs on a default build.
 ARG AGENT_UID=1000
 ARG AGENT_GID=1000
-RUN groupadd --gid ${AGENT_GID} agent \
- && useradd --uid ${AGENT_UID} --gid ${AGENT_GID} --create-home --shell /bin/bash agent
+RUN groupmod -o -g ${AGENT_GID} node \
+ && usermod -o -u ${AGENT_UID} -g ${AGENT_GID} -d /home/agent -m -l agent node
  
-USER agent
-WORKDIR /workspace
+USER ${AGENT_UID}:${AGENT_GID}
+WORKDIR /home/agent
+ 
+# Sandcastle bind-mounts the worktree and sets the working directory at
+# container start; the container just needs to stay alive until then.
+ENTRYPOINT ["sleep", "infinity"]
Show full Dockerfile (highlighted)
# Sandbox image for the Docs From Codebase workflow.
# Node 22 + git + the Claude Code CLI, running as a non-root `agent` user.
# Add your project's toolchain (python, go, ...) here if the agent needs to run
# it to understand the project.
FROM node:22-bookworm

RUN apt-get update && apt-get install -y --no-install-recommends \
      git \
      curl \
      jq \
      ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# Claude Code CLI (the agent runtime).
RUN npm install -g @anthropic-ai/claude-code

# Non-root agent user. `sandcastle docker build-image` aligns AGENT_UID/GID to
# the host user via --build-arg to avoid permission errors on bind mounts.
# node:22-bookworm already ships a "node" user at UID/GID 1000, so we RENAME it
# (the stock Sandcastle template pattern) — groupadd/useradd would collide with
# the existing IDs on a default build.
ARG AGENT_UID=1000
ARG AGENT_GID=1000
RUN groupmod -o -g ${AGENT_GID} node \
 && usermod -o -u ${AGENT_UID} -g ${AGENT_GID} -d /home/agent -m -l agent node

USER ${AGENT_UID}:${AGENT_GID}
WORKDIR /home/agent

# Sandcastle bind-mounts the worktree and sets the working directory at
# container start; the container just needs to stay alive until then.
ENTRYPOINT ["sleep", "infinity"]

README

Docs From Codebase

Point one Claude Code agent at an under-documented repository and get back a real docs/ set — a getting-started guide, an architecture overview, and per-module reference pages — grounded in the code that actually exists, not in guesses.

What it does

Most codebases are documented badly or not at all, and the docs that do exist rot the moment the code moves. This workflow reads your repository and writes the documentation a new contributor actually needs. Because dependencies are installed in the sandbox, the agent can run the project to confirm the commands it writes down really work — so the getting-started guide is verified, not assumed. It commits each doc incrementally and stops when the set is complete, emitting <promise>DOCS_DONE</promise>.

How it works

main.ts runs a single claude-opus-4-8 agent in a Docker sandbox for up to four passes. An onSandboxReady hook runs npm install once so the project is runnable, and the prompt seeds the agent with a shell-expanded repository map via a !`git ls-files | head -300` block — giving it an instant sense of the layout before it opens a single file. Across passes it writes docs/getting-started.md, docs/architecture.md, and one docs/reference/<module>.md per significant module, committing as it goes.

The topology is a loop: install → map → write & commit docs → next pass.

Requirements

Set CLAUDE_CODE_OAUTH_TOKEN in .sandcastle/.env (run claude setup-token on your host). The default sandbox hook runs npm install; if your project is not npm-based, adjust or remove that hook in .sandcastle/main.ts and add your toolchain to the Dockerfile. Build the image once with npx @ai-hero/sandcastle docker build-image, then run it with npx tsx .sandcastle/main.ts. Docs land in docs/.