AgentKindergarten – daycare for your AI coding agents

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

3 Commits

3 Commits

.github/workflows

.github/workflows

landing

landing

packages

packages

.dockerignore

.dockerignore

.gitattributes

.gitattributes

.gitignore

.gitignore

DEPLOY.md

DEPLOY.md

Dockerfile

Dockerfile

LICENSE

LICENSE

README.md

README.md

SPEC.md

SPEC.md

biome.json

biome.json

package.json

package.json

pnpm-lock.yaml

pnpm-lock.yaml

pnpm-workspace.yaml

pnpm-workspace.yaml

tsconfig.base.json

tsconfig.base.json

Repository files navigation

Daycare for your AI coding agents — so you can log off without logging off.

Do you have a spouse who nags every time you vibe-code for 72 hours straight? Does a "family picnic" feel like a hostage negotiation between you and a perfectly good merge conflict? Do you need to peel yourself off the keyboard to go pick up your kid who's only been waiting at school for an hour?

Congratulations: these are the ordinary, unbearable hardships of the modern vibe coder, and I built the cure.

AgentKindergarten streams your entire dev environment straight to your pocket. Your agents keep grinding on your home PC while your body attends the picnic. You nod. You say "mhm." You watch Claude refactor the auth layer from the potato-salad table — one thumb on your phone, one hand accepting a paper plate you did not ask for.

Kid wants a push on the swing? Push a commit instead. From the swing. That's multitasking.

In-law asking about your "career plans"? Turn the phone around — you are, at this very moment, supervising seven autonomous engineers from a lawn chair. They will stop asking.

Someone shouts "burgers are ready"? So is your dev server on localhost:3000 — open it live through the tunnel before the ketchup comes out.

Your agents never take a day off. Now you don't have to either — you just do it somewhere with grass.

What you're neglecting your family for

🧒 Students — every agent session streamed live as a real terminal you can type into (yes, from the bench).

🏫 Classroom — one dashboard for every session on your machine, so you can ignore them all in one place.

📺 Show & Tell — dev servers your agents start (localhost:3000 & friends) are auto-detected and openable live through the tunnel. From the car. In the pickup line. Engine running.

📋 Roll call — see at a glance which daemons and sessions are present — i.e. who's actually working while you're "present."

🪞 Same session, everywhere — a session lives on your PC; terminal, browser, and phone are all just views of it. Start it at your desk, keep going from the in-laws' bathroom, come back to your desk. No fork, no handoff, no witnesses.

🍎 Miss Clanker, the Teacher — opt-in report cards for the whole class: each student's assignment, how it's going, and the receipts to prove it. She nags the agents so you don't have to — outsource the nagging at last. Graded by your own claude CLI, any agent CLI, or an OpenRouter key; watch her grade live, token bill and all.

🖐️ Raised hands — a student that stalls, errors out, or sits at a permission prompt raises its hand and web-pushes your phone — a genuine emergency you can use to excuse yourself from grace at Thanksgiving.

I accept no liability for missed swing-pushes, cold burgers, or the slow dawning realization on your child's face.

How it works

Phone/Browser ──HTTPS/WSS──▶ Relay (your VPS) ◀──WSS (outbound)── Daemon (your PC) │ │ └─ hosts web UI + auth └─ wraps agent CLIs in PTYs, pure pass-through, no storage watches ports, proxies previews

The daemon runs on your dev machine and dials out — no port-forwarding, no inbound firewall holes.

The relay is a tiny self-hosted server: it authenticates you and routes traffic. It is a pure pass-through — no database, no logs of your sessions, nothing persisted.

Your agent credentials never leave your machine. The daemon simply runs the CLIs you already have installed and logged in (your own Claude Code login, your own API keys). AgentKindergarten never touches agent auth tokens.

Using it

The daemon exposes one CLI: agk. You run it on the machine your agents live on.

First-time setup (once)

npm install -g agentkindergarten # installs the agk command

agk init --relay wss://your.domain --token agk start # connects to the relay; leave it running

Then open your relay in a browser (or the PWA on your phone), log in with your access token, and you'll see this machine under 📋 Roll call. For always-on (survives reboots), see the Task Scheduler recipe in DEPLOY.md.

One machine runs exactly one daemon. agk start refuses to start a second one (pass --force to override). If something looks off, check ~/.agentkindergarten/daemon.out.log.

The one-liner you'll use every day

agk claude

Type this instead of claude. The session is born in the classroom and attached to your terminal at the same time — so your terminal, browser, and phone are three views of the one session. It never forks. All agent flags pass straight through:

You type You get

agk claude fresh Claude session, mirrored everywhere

agk claude -c continue this folder's latest conversation, mirrored

agk claude --resume resume an exact conversation, mirrored

agk codex same, for Codex

Press Ctrl+] to detach your terminal — the session keeps running in the classroom; reattach any time with agk attach.

Command reference

Command What it does

agk start Start the daemon: connect to the relay and wait for students. Leave it running.

agk claude [args…] Enroll + attach in one step. Start Claude in the classroom and in this terminal. (agk codex too.)

agk run "" --name Enroll a command as a student without attaching (streams to the classroom only). Add --attach to also attach.

agk attach Attach this terminal to an existing student, tmux-style. Ctrl+] detaches without killing it.

agk ls List the students currently in the classroom.

agk rename Re-label a student — then agk attach works.

agk stop Send a student home (kill the process); its scrollback stays in the classroom.

agk close Remove a student tile entirely (kills it first if still running).

agk teacher [options] Hire Miss Clanker: --claude grades with your own claude -p (no key), --cli "" uses any agent CLI, --key uses OpenRouter. --off fires her.

agk watch [options] The watchful teacher: raised-hand alerts for stalls/errors/permission prompts (--stall , --escalate on for a Teacher one-liner).

agk skills [install] List the bundled Claude Code skills; install copies them into ~/.claude/skills.

agk init [options] (Re)create the daemon config at ~/.agentkindergarten/config.json.

Sessions live on your PC as OS processes; closing a terminal or browser never affects them. Your agent's own conversation history persists on disk and is resumable (agk claude -c / --resume).

Driving it from Claude Code (optional skills)

If you use Claude Code, four skills ship with the package — install them once and control the classroom from inside a chat, great for "I'm mid-conversation and want to continue on my phone":

agk skills install # copies them into ~/.claude/skills

(From a repo clone instead: copy the folders in packages/daemon/skills/ into ~/.claude/skills/.)

In a Claude Code chat What it does

/kindergarten-mirror [name] Mirror this conversation: enrolls it with full history and opens a local attached terminal — phone + PC, same session, one command.

/kindergarten-join Hand this conversation off to the classroom (phone/web only).

/kindergarten-set Name (or rename) this conversation's classroom session so agk attach works.

/kindergarten-detach Pull this conversation back out of the classroom and continue it in a plain local terminal.

Report cards & raised hands (Miss Clanker)

agk teacher --claude # hire Miss Clanker — grades with your own claude CLI, no key needed agk watch --stall 10 # a student that's silent for 10 min raises its hand 🖐️

Report cards (📋 Reports in the web UI) are opt-in: each student gets graded on what its assignment was, how it's going, and the receipts (transcript excerpts) to back it up. Watch the grading happen live — Miss Clanker's own token bill included.

Backends: --claude (your existing subscription, nothing leaves your machine), --cli "codex exec" (any agent CLI), or --key (transcripts go to OpenRouter — your call).

Raised hands are on by default and fully local: stalls, errors, and permission prompts flag the student in the classroom; enable alerts on the phone to get a web-push. agk watch --escalate on adds a one-line Teacher summary of why the hand is up.

🔒 Security & trust model

Nothing on your PC listens publicly. The daemon dials out to your relay — no port-forwarding, no inbound firewall holes. Kill the daemon and your PC is a stranger to the internet again.

Two secrets:

Access token — your browser login. HTTPS-only, rate-limited, and it mints a signed cookie whose key is derived from the token itself — so rotating the access token on the relay instantly logs everyone out. That's your kill switch.

Pairing token — authenticates the daemon to the relay. Lives in ~/.agentkindergarten/config.json.

Anyone holding your access token can drive the machine the daemon runs on — that is literally the product. Use a long random token, always run the relay behind HTTPS, and treat the token like an SSH key.

Because the daemon trusts the relay socket, a compromised relay is your real worst case. Two daemon-side controls defend against that — enforced on the daemon, so they hold even if the relay/VPS is fully owned:

Flag (on agk init) Effect

--lock-commands The daemon spawns only its built-in presets (claude, codex, shell) — a hijacked relay can't launch arbitrary commands.

--view-only The daemon drops all terminal input coming from the relay — the web UI/phone can watch but can't type. Only a local agk attach can drive.

Two more protections are always on: the preview tunnel can only reach ports your own students opened (no reaching other localhost services like a database or model server), and a browser can only type into a session it explicitly attached.

Recommended posture for a public or shared relay: agk init --lock-commands --view-only.

Try it locally (5 minutes)

Everything below runs on one machine — the same wiring as production, just with the relay on localhost.

pnpm install pnpm -r build

1. relay (terminal 1)

$env:AGK_INSECURE='1'; $env:AGK_ACCESS_TOKEN='pick-a-token'; $env:AGK_PAIRING_TOKEN='pick-another' node packages/relay/dist/server.js

2. daemon (terminal 2)

node packages/daemon/dist/cli.js init --relay ws://127.0.0.1:8787 --token pick-another node packages/daemon/dist/cli.js start

3. open http://127.0.0.1:8787/app/ — log in with pick-a-token,

hit "+ New student", run claude (or anything), and watch it live.

Start a dev server inside a student (e.g. pnpm dev) and its port shows up under 📺 Show & Tell within seconds — click "open live" to view the app through the tunnel.

Deploying the relay on a VPS

See DEPLOY.md — Docker Compose brings up the relay + Caddy (automatic Let's Encrypt HTTPS); the daemon on your PC connects with agk init --relay wss://your.domain. Includes a Windows Task Scheduler recipe so the daemon stays up while you're away. The relay image is verified to build and serve.

Development

pnpm install pnpm -r build # typecheck + bundle everything pnpm -r test # unit tests across daemon/relay/shared (incl. a real ConPTY spawn) pnpm check # biome lint + format

End-to-end suites (start relay + daemon first, as in "Try it locally" with token test-access / test-pair):

node packages/relay/scripts/e2e-m3.mjs # auth + session streaming round-trip node packages/relay/scripts/e2e-m4.mjs phase1 # multi-session + backlog

[truncated for AI cost control]