Literature Review Builder
MIT↓ 0 downloadsReads a sources.md list of papers, fetches each one, and builds a structured literature review — per-source summary of question, method, finding, and limitation — then synthesizes the themes, disagreements, and open gaps across the whole set.
Topology
Disclosures
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.
cp .env.example .env
Sandbox hooks
Commands executed inside the sandbox container.
None declared.
Network access
Fetches each source URL in sources.md via curl.
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 Literature Review Builder workflow.+# Node 22 + git + curl (the reviewer fetches each source URL) + the Claude Code+# CLI, running as a non-root `agent` user.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=1000ARG 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 Literature Review Builder workflow.
# Node 22 + git + curl (the reviewer fetches each source URL) + the Claude Code
# CLI, running as a non-root `agent` user.
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"]
# Auth for the Claude Code reviewer.
# Run `claude setup-token` on your host to generate a token, then paste it here
# in your local .sandcastle/.env (never commit the real .env).
CLAUDE_CODE_OAUTH_TOKEN=
import { run, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
// A single Opus reviewer reads the sources.md list committed in your repo,
// fetches each source, and builds a structured literature review. The host hook
// seeds .env into the worktree. The review-prompt.md `cat sources.md` block puts
// the source list in front of the agent; it then fetches each one with curl (see
// review-prompt.md) — this is why the manifest discloses network + shell
// expansion. The loop lets it work through a long list across iterations,
// stopping early when it emits <promise>REVIEW_DONE</promise>.
const review = await run({
name: "literature-review",
agent: claudeCode("claude-opus-4-8", { effort: "high" }),
sandbox: docker(),
promptFile: ".sandcastle/review-prompt.md",
maxIterations: 4,
completionSignal: "<promise>REVIEW_DONE</promise>",
hooks: {
host: {
onWorktreeReady: [{ command: "cp .env.example .env" }],
},
},
});
console.log(`Reviewer finished with signal: ${review.completionSignal ?? "none"}`);
Build a literature review
You are a research librarian. Work through the source list committed in
sources.md, read each source, and assemble a structured literature review.
The source list
!cat sources.md
Your task
For every source listed above, fetch it with the Bash tool (for example
curl -sL --max-time 30 "<url>") and read it carefully. Then write and
incrementally update review/literature-review.md.
Per-source entries
Under a Sources heading, add one entry per source with these fields:
- Citation — title and URL (and author/year if you can find them).
- Research question — what the source set out to answer.
- Method — how they investigated it (data, study design, sample).
- Key finding — the main result, stated concretely.
- Limitation — the most important caveat or weakness.
If a fetch fails or a source is paywalled and you cannot read the substance, say so in that entry rather than inventing a summary. Never fabricate a finding, method, or citation.
Synthesis
After the per-source entries, add a Synthesis section that covers:
- Themes — where the sources converge, and how the conversation has evolved.
- Disagreements — where findings conflict, and the likely reasons.
- Gaps — questions the literature has not yet answered — the openings for new work.
Working across iterations
Commit your progress as you go (for example review: summarize <source>), so a
long source list can be worked through across several iterations. When every
source in sources.md has an entry and the synthesis is complete, output
<promise>REVIEW_DONE</promise>.
README
Literature Review Builder
Hand it a reading list and get back a structured literature review — every source read, summarized on the same rubric, and synthesized into the themes, disagreements, and open gaps that actually matter for your work.
What it does
You commit a sources.md file listing the papers, articles, or reports you want
reviewed (titles and URLs). A Claude Code reviewer reads that list, fetches
each source, and writes review/literature-review.md.
Each source gets a consistent entry: its citation, the research question it set out to answer, the method it used, its key finding, and its most important limitation. If a source is paywalled or a fetch fails, the reviewer says so rather than inventing a summary. After the per-source entries, it writes a Synthesis section: the themes where sources converge, where their findings conflict and why, and the gaps the literature has not yet closed — the openings for new work.
How it works
main.ts runs a single Opus reviewer. A !`cat sources.md` block in the
prompt puts your reading list in front of the agent — this is why the manifest
discloses shell expansion — and the agent then fetches each URL with curl
inside the sandbox, which is why network access is disclosed too. A host hook
seeds .env into the worktree. The run loops (up to four iterations) so a long
list can be worked through incrementally, committing progress and stopping early
when it emits <promise>REVIEW_DONE</promise>. The topology is a single
summarize-and-synthesize node with a continue loop.
Requirements
Set CLAUDE_CODE_OAUTH_TOKEN in .sandcastle/.env (run claude setup-token).
Add your sources to a sources.md at the repo root. Build the image once with
npx @ai-hero/sandcastle docker build-image, then run
npx tsx .sandcastle/main.ts. Everything the reviewer fetches is content from
the URLs you listed; nothing is sent anywhere but the model.