InferHaven/agent-skills / codetrain
codetrain
FlaggedCodeTrain is an open-source Socratic coding tutor with a local lesson page where the learner writes every line while the agent sets small steps, gives hints and reviews the work without putting the solution into the lesson. Use when the user wants to be taught/walked through code one tiny step at a time — triggers like "teach me this code", "walk me through this", "hold my hand", "explain step by step", "tutor me", "guide me through", "I want to learn this", or asks for a safe practice exercise to learn a concept.
app/server.py
View on GitHub#!/usr/bin/env python3
"""
CodeTrain — local presentation server.
A presentation layer. It serves a responsive tutoring UI and a tiny JSON state
API. It executes user code ONLY inside an optional, sandboxed throwaway container
(bash "Run"); never otherwise.
Contract:
- Claude (the tutor) writes session.json each turn: the current step, hints,
feedback, tests, and the running "learned" list.
- The browser polls GET /api/state ~every 1.2s and renders it.
- User actions in the browser (submitting code, asking for a hint, choosing a
level/goal) POST to /api/event. The server appends them to session.json's
`inbox` queue and, for submissions, writes the code to the workspace file.
- Claude drains `inbox` on its next turn, reviews, runs tests with its OWN
tools, and updates session.json again.
Config via environment (or flags):
TUTOR_SESSION path to session.json (required)
TUTOR_WORKSPACE root dir for writing code files (required)
TUTOR_STATIC static asset dir (default: ./static next to this file)
TUTOR_HOST bind host (default 127.0.0.1 — loopback only)
TUTOR_PORT preferred port (default 7341; falls forward if busy)
On start it writes `url.txt` and `server.pid` next to session.json so the tutor
can discover/reuse a running instance and clean it up later.
"""
import argparse
import fnmatch
import json
import os
import shutil
import socket
import subprocess
import sys
import tempfile
import threading
import time
import uuid
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import answer_guard # noqa: E402 (a sibling file in this folder)
HERE = os.path.dirname(os.path.abspath(__file__))
LOCK = threading.Lock()
# A worker takes its content security policy from the response that delivered its script, so
# the two workers get the study page's: scripts and fetches from here and from jsDelivr, where
# Pyodide and the packages it bundles come from, and nowhere else. Without it, the Python worker's
# fallback for a package Pyodide does not bundle (micropip) would fetch from PyPI on this page while
# the study page blocks it, and the skill's README promises Pyodide from jsDelivr as the only
# download. The page itself carries no policy.
WORKER_SCRIPTS = ("pyodide-worker.js", "js-worker.js")
WORKER_POLICY = ("default-src 'self'; script-src 'self' 'unsafe-eval' https://cdn.jsdelivr.net; "
"connect-src 'self' https://cdn.jsdelivr.net")
# Files that look like secrets or credentials, matched case-insensitively on the basename. The
# CLI's repo reader refuses these before a path can ever be cited, but in the open skill the agent
# writes `repo_cited` itself, so this server refuses them too: a secret never reaches the page,
# whoever wrote the list. Mirrors agent/code_trainer.py `_SECRET_GLOBS` and the hosted reader's
# copy; test_repo_fetch.py holds the three equal.
_SECRET_GLOBS = (
".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx", "*.pkcs12",
"id_rsa*", "id_dsa*", "id_ecdsa*", "id_ed25519*", "*.keystore", "*.jks",
".netrc", "_netrc", ".npmrc", ".pypirc", ".pgpass", ".git-credentials",
"*.kdbx", "credentials", "credentials.json", "service-account*.json",
"*.secret", ".secrets", "secrets.json", "secrets.yml", "secrets.yaml", "client_secret*",
".htpasswd", "*.ovpn", "wg*.conf",
# PuTTY private keys, and Terraform state: plain-text secrets. `*.tfstate.*` is the backups.
"*.ppk", "*.tfstate", "*.tfstate.*",
)
# Env templates are meant to be copied and committed: placeholders, not credentials.
_ENV_TEMPLATE_OK = (
".env.example", ".env.sample", ".env.template", ".env.dist", ".env.defaults",
)
def _is_secret(path):
name = os.path.basename(path).lower()
if name in _ENV_TEMPLATE_OK:
return False
return any(fnmatch.fnmatch(name, g) for g in _SECRET_GLOBS)
def _git_ignored(root, rel):
"""Whether git ignores `rel` under `root`. False when `root` is not a git checkout or git is
missing, so the secret list above stays the backstop."""
git = shutil.which("git")
if not git or not os.path.exists(os.path.join(root, ".git")):
return False
try:
proc = subprocess.run([git, "-C", root, "check-ignore", "-q", "--", rel],
capture_output=True, timeout=10)
except (OSError, subprocess.SubprocessError):
return False
return proc.returncode == 0
# What ONE cited file may weigh when the learner opens it. Matches repo_fetch.MAX_VIEW_BYTES
# on the hosted side so a lesson reads the same in both places.
REPO_VIEW_BYTES = 120_000
_DONE_GRACE = 90 # seconds to keep serving `done` (recap + confetti), then self-exit
_done_timer = None
def _arm_done_shutdown():
"""Once the browser has seen phase:done, keep serving briefly so the recap +
confetti render, then exit so the detached server doesn't linger. Idempotent.
(Stopping the server the instant `done` is patched races this poll and freezes
the page on "reviewing" — let the server retire itself instead.)"""
global _done_timer
if _done_timer is None:
_done_timer = threading.Timer(_DONE_GRACE, lambda: os._exit(0))
_done_timer.daemon = True
_done_timer.start()
CONTENT_TYPES = {
".html": "text/html; charset=utf-8",
".css": "text/css; charset=utf-8",
".js": "application/javascript; charset=utf-8",
".woff2": "font/woff2",
".svg": "image/svg+xml",
}
def load_session(path):
try:
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
except (FileNotFoundError, json.JSONDecodeError):
return {
"version": 1,
"phase": "intake",
"title": "Your tutor is setting up…",
"tutor_status": "thinking",
"inbox": [],
"learned": [],
}
def active_step(s):
"""The step the user is currently on — supports steps[] (new) or step (legacy)."""
steps = s.get("steps")
if isinstance(steps, list) and steps:
idx = ((s.get("progress") or {}).get("step", 1) or 1) - 1
if 0 <= idx < len(steps):
return steps[idx]
return s.get("step") or {}
def _read_sandbox_file(workspace, rel, cap=200_000):
"""Current content of `rel` in the sandbox workspace, or None if absent/unreadable.
Path-scoped via safe_join (same guard as the submit write)."""
if not rel:
return None
try:
target = safe_join(workspace, rel)
with open(target, "r", encoding="utf-8") as f:
return f.read(cap)
except (OSError, ValueError):
return None
def overlay_sandbox_files(workspace, data):
"""Make the active step's editor content reflect the LIVE sandbox file, not the
intake-time pristine `starter_code`. The sandbox is the single source of truth: a
submit writes the edited file there (see do_POST), so when a later step edits the
same file the editor must show that committed change instead of reverting.
Mutates only the in-memory copy returned to the browser — session.json on disk is
left untouched (the agent owns it). No-op for files not yet written to the sandbox."""
if not workspace:
return data
step = active_step(data)
flist = step.get("files")
if isinstance(flist, list) and flist:
for fo in flist:
body = _read_sandbox_file(workspace, fo.get("file"))
if body is not None:
fo["starter_code"] = body
if flist[0].get("starter_code") is not None:
step["starter_code"] = flist[0]["starter_code"]
return data
body = _read_sandbox_file(workspace, step.get("file"))
if body is not None:
step["starter_code"] = body
return data
def save_session(path, data):
tmp = path + ".tmp"
with open(tmp, "w", encoding="utf-8") as f:
json.dump(data, f, indent=2)
os.replace(tmp, path) # atomic: readers never see a half-written file
def read_profile():
"""Read the local learner profile + a recent-history index (read-only).
Touches only ~/.codetrain — never executes anything. Powers the UI's Progress
drawer; the browser fetches it on demand (no tutor turn, no tokens)."""
home = os.path.expanduser("~")
base = os.path.join(home, ".codetrain")
if not os.path.isdir(base) and os.path.isdir(os.path.join(home, ".claude", "codetrain")):
base = os.path.join(home, ".claude", "codetrain") # legacy location (pre-relocation)
prof = {}
try:
with open(os.path.join(base, "profile.json"), "r", encoding="utf-8") as f:
prof = json.load(f)
except (FileNotFoundError, json.JSONDecodeError, OSError):
prof = {}
hist = []
hdir = os.path.join(base, "history")
try:
names = sorted((n for n in os.listdir(hdir) if n.endswith(".md")), reverse=True)
except OSError:
names = []
for n in names[:12]: # most recent dozen — filenames sort by date
stem = n[:-3]
if len(stem) >= 11 and stem[4] == "-" and stem[7] == "-" and stem[10] == "-":
date, slug = stem[:10], stem[11:] # <YYYY-MM-DD>-<slug>
else:
date, slug = "", stem
title = slug.replace("-", " ").strip() or stem
try:
with open(os.path.join(hdir, n), "r", encoding="utf-8") as f:
for line in f: # first non-empty line = title
s = line.strip()
if s:
title = s.lstrip("# ").strip() or title
break
except OSError:
pass
hist.append({"date": date, "slug": slug, "title": title})
return {"profile": prof if isinstance(prof, dict) else {}, "history": hist}
def safe_join(root, rel):
"""Resolve rel under root, refusing path traversal."""
root_r = os.path.realpath(root)
target = os.path.realpath(os.path.join(root_r, rel))
if target != root_r and not target.startswith(root_r + os.sep):
raise ValueError("path traversal blocked: %r" % rel)
return target
# ---- optional sandboxed bash runner -----------------------------------------
# The ONLY place the server executes user code, and only inside a throwaway,
# network-disabled, resource-limited container. If no container runtime + usable
# image are present, this stays disabled and the browser falls back to Claude-run.
RUN_TIMEOUT = 15
_IMG_PREFS = ("alpine", "busybox", "bash", "ubuntu", "debian")
def detect_runtime():
for rt in ("podman", "docker"):
if not shutil.which(rt):
continue
try:
out = subprocess.run([rt, "images", "--format", "{{.Repository}}:{{.Tag}}"],
capture_output=True, text=True, timeout=8)
except Exception:
continue
imgs = [l.strip() for l in (out.stdout or "").splitlines() if l.strip() and l != "<none>:<none>"]
for pref in _IMG_PREFS:
for img in imgs:
if img.split("/")[-1].split(":")[0] == pref:
return rt, img
return None, None
RUNTIME, RUN_IMAGE = detect_runtime()
def run_in_container(workspace, code):
"""One-shot, sandboxed bash exec → {stdout, stderr, exit} or {error}.
The container runs under `--init` and has a name, and a timeout ends in `kill <name>`.
Killing the docker/podman CLI never stops its container, and without an init the
learner's program is PID 1, which ignores any signal it has no handler for: a loop that
"timed out" kept a CPU busy with nothing left to stop it. (CodeTrain's hosted sandbox
runner had the same bug and the same fix.)"""
if not RUNTIME or not RUN_IMAGE:
return {"error": "no container runtime"}
path = None
name = "codetrain-run-%s" % uuid.uuid4().hex[:12]
try:
fd, path = tempfile.mkstemp(prefix=".run-", suffix=".sh", dir=workspace)
with os.fdopen(fd, "w") as f:
f.write(code or "")
cmd = [RUNTIME, "run", "--rm", "--init", "--name", name, "--network=none",
"--memory=256m", "--pids-limit=128",
"-v", "%s:/work" % os.path.realpath(workspace), "-w", "/work",
RUN_IMAGE, "sh", "/work/" + os.path.basename(path)]
try:
proc = subprocess.run(cmd, capture_output=True, text=True, timeout=RUN_TIMEOUT)
except subprocess.TimeoutExpired:
subprocess.run([RUNTIME, "kill", name], capture_output=True, timeout=15)
return {"stdout": "", "stderr": "timed out", "exit": 124}
return {"stdout": proc.stdout, "stderr": proc.stderr, "exit": proc.returncode}
except Exception as e:
return {"error": str(e)}
finally:
if path:
try:
os.remove(path)
except Exception:
pass
class Handler(BaseHTTPRequestHandler):
session_path = "" # set in main()
workspace = ""
static_dir = ""
def log_message(self, *args): # keep the terminal quiet
pass
def _send(self, code, body, ctype="application/json; charset=utf-8", headers=None):
if isinstance(body, str):
body = body.encode("utf-8")
self.send_response(code)
self.send_header("Content-Type", ctype)
self.send_header("Content-Length", str(len(body)))
self.send_header("Cache-Control", "no-store")
for name, value in (headers or {}).items():
self.send_header(name, value)
self.end_headers()
self.wfile.write(body)
def _serve_static(self, name):
try:
path = safe_join(self.static_dir, name)
except ValueError:
return self._send(403, "forbidden", "text/plain")
if not os.path.isfile(path):
return self._send(404, "not found", "text/plain")
with open(path, "rb") as f:
data = f.read()
ext = os.path.splitext(path)[1]
extra = ({"Content-Security-Policy": WORKER_POLICY}
if os.path.basename(path) in WORKER_SCRIPTS else None)
self._send(200, data, CONTENT_TYPES.get(ext, "application/octet-stream"), extra)
def do_GET(self):
p = self.path.split("?")[0]
if p in ("/", "/index.html"):
return self._serve_static("index.html")
if p == "/api/state":
with LOCK:
data = load_session(self.session_path)
# Seed the editor from the live sandbox file (the source of truth) so a
# change committed in an earlier step survives into later steps on the same file.
overlay_sandbox_files(self.workspace, data)
if data.get("phase") == "done":
_arm_done_shutdown()
# The page sees the session with any span that writes a step out held back
# (answer_guard.py); session.json on disk stays as the tutor wrote it.
return self._send(200, json.dumps(answer_guard.guard_state(data)))
if p == "/api/runtime":
return self._send(200, json.dumps({"bash": bool(RUNTIME and RUN_IMAGE), "runtime": RUNTIME}))
if p == "/api/patch-pending":
# The FULL pending patch diff (the state payload carries a capped one) — read from
# the local stash so the learner can inspect every line before Apply writes it.
pend = os.path.join(os.path.dirname(self.session_path), "patch_pending.json")
try:
with open(pend, "r", encoding="utf-8") as f:
data = json.load(f)
except (FileNotFoundError, json.JSONDecodeError):
return self._send(404, json.dumps({"error": "no pending patch"}))
return self._send(200, json.dumps({"target": data.get("target"), "diff": data.get("diff", "")}))
if p == "/api/profile":
return self._send(200, json.dumps(read_profile()))
if p == "/api/repo-file":
return self._handle_repo_file()
if p.startswith("/") and "/" not in p[1:]: # flat static files only
return self._serve_static(p[1:])
self._send(404, "not found", "text/plain")
def _handle_repo_file(self):
"""One file from the learner's own checkout, for reading beside the lesson that cites it.
THE SESSION'S CITATION LIST IS THE ENTIRE INPUT SURFACE: a path nobody cited can never be
read, the same shape as the hosted side, where the allowlist is what the lesson named. In
the CLI, `repo_cited` comes from the repo reader in code_trainer.py, which already refuses
secrets, gitignored files and binaries; in the open skill the agent writes it, so every
path is checked here as well, the link it resolves to included: inside `repo_root`, not a
secret, not ignored by git, and text. A refusal reads like any unknown path.
"""
from urllib.parse import parse_qs, urlparse
rel = (parse_qs(urlparse(self.path).query).get("path") or [""])[0]
with LOCK:
data = load_session(self.session_path)
root = data.get("repo_root")
if not root or rel not in set(data.get("repo_cited") or []):
return self._send(404, json.dumps({"error": "no such file in this lesson"}))
try:
target = safe_join(root, rel)
except ValueError:
return self._send(404, json.dumps({"error": "no such file in this lesson"}))
if (_is_secret(rel) or _is_secret(target)
or _git_ignored(root, os.path.relpath(target, os.path.realpath(root)))):
return self._send(404, json.dumps({"error": "no such file in this lesson"}))
try:
raw = open(target, "rb").read(REPO_VIEW_BYTES + 1)
except OSError:
return self._send(404, json.dumps({"error": "that file could not be read"}))
try:
text = raw.decode("utf-8")
except UnicodeDecodeError:
return self._send(415, json.dumps({"error": "that file isn't text"}))
if "\x00" in text:
return self._send(415, json.dumps({"error": "that file isn't text"}))
try:
size = os.path.getsize(target)
except OSError:
size = len(raw)
return self._send(200, json.dumps({
"path": rel,
"content": text[:REPO_VIEW_BYTES],
"bytes": size,
"truncated": len(raw) > REPO_VIEW_BYTES,
}))
def _handle_run(self):
length = int(self.headers.get("Content-Length", 0) or 0)
try:
body = json.loads(self.rfile.read(length) or b"{}")
except json.JSONDecodeError:
return self._send(400, json.dumps({"ok": False, "error": "bad json"}))
if (body.get("lang") or "").lower() not in ("bash", "sh", "shell"):
return self._send(200, json.dumps({"error": "unsupported lang"}))
return self._send(200, json.dumps(run_in_container(self.workspace, body.get("code", ""))))
def do_POST(self):
p = self.path.split("?")[0]
if p == "/api/run":
return self._handle_run()
if p != "/api/event":
return self._send(404, "not found", "text/plain")
length = int(self.headers.get("Content-Length", 0) or 0)
try:
ev = json.loads(self.rfile.read(length) or b"{}")
except json.JSONDecodeError:
return self._send(400, json.dumps({"ok": False, "error": "bad json"}))
ev["ts"] = time.time()
with LOCK:
s = load_session(self.session_path)
s.setdefault("inbox", []).append(ev)
t = ev.get("type")
if t == "intake":
s["level"] = ev.get("level")
s["goal"] = ev.get("goal")
s["guidance"] = ev.get("guidance") or "balanced"
# Tutor voice, read by tutor.persona_block on every turn. Pinned at intake so a
# lesson keeps the voice it was authored in.
s["persona"] = ev.get("persona") or "plain"
if ev.get("model"):
s["model"] = ev.get("model") # per-session model (Sonnet/Haiku) for the loop
s["tutor_status"] = "thinking"
elif t == "submit":
code = ev.get("code", "")
files_map = ev.get("files") if isinstance(ev.get("files"), dict) else None
s["submission"] = {"ts": ev["ts"], "code": code, "note": ev.get("note", ""),
"files": files_map or {}}
# Write each edited file to its sandbox path (multi-file step), else the single
# active-step file. safe_join scopes everything to the sandbox workspace.
writes = files_map.items() if files_map else (
[(active_step(s).get("file"), code)] if active_step(s).get("file") else [])
for rel, fcode in writes:
if not rel:
continue
try:
target = safe_join(self.workspace, rel)
os.makedirs(os.path.dirname(target), exist_ok=True)
with open(target, "w", encoding="utf-8") as f:
f.write(fcode if isinstance(fcode, str) else "")
except Exception as e:
save_session(self.session_path, s)
return self._send(200, json.dumps({"ok": False, "error": str(e)}))
s["tutor_status"] = "thinking"
elif t in ("question", "end"):
s["tutor_status"] = "thinking"
save_session(self.session_path, s)
self._send(200, json.dumps({"ok": True}))
def find_port(host, start):
for port in range(start, start + 50):
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
s.bind((host, port))
s.close()
return port
except OSError:
s.close()
continue
return start
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--session", default=os.environ.get("TUTOR_SESSION"))
ap.add_argument("--workspace", default=os.environ.get("TUTOR_WORKSPACE"))
ap.add_argument("--static", default=os.environ.get("TUTOR_STATIC", os.path.join(HERE, "static")))
ap.add_argument("--host", default=os.environ.get("TUTOR_HOST", "127.0.0.1"))
ap.add_argument("--port", type=int, default=int(os.environ.get("TUTOR_PORT", "7341")))
args = ap.parse_args()
if not args.session or not args.workspace:
print("ERROR: --session and --workspace are required", file=sys.stderr)
sys.exit(2)
tutor_dir = os.path.dirname(args.session)
os.makedirs(tutor_dir, exist_ok=True)
Handler.session_path = args.session
Handler.workspace = args.workspace
Handler.static_dir = args.static
port = find_port(args.host, args.port)
httpd = ThreadingHTTPServer((args.host, port), Handler)
url = "http://%s:%d" % (args.host, port)
# discovery + teardown breadcrumbs for the tutor
with open(os.path.join(tutor_dir, "url.txt"), "w") as f:
f.write(url + "\n")
with open(os.path.join(tutor_dir, "server.pid"), "w") as f:
f.write(str(os.getpid()) + "\n")
print("TUTOR_URL=" + url, flush=True)
try:
httpd.serve_forever()
except KeyboardInterrupt:
pass
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |