Project Info
Inspiration
In 2026, the AI community has gone all in on two ideas at once: agents that can act on their own, and continual learning that lets models keep getting better. The most ambitious version of the field sits right where those two meet. Automating research itself, and specifically AI research, so that a system can start to improve itself. The rough shape of this has felt possible for a while. When AutoGPT showed up in 2023 it proved you could chain a model into something that plans and acts, even if it mostly spun in circles. The tooling has caught up a lot since then. Andrej Karpathy called natural language the hottest new programming language, and leaders at frontier labs now talk openly about a large and growing share of their code being written by models instead of by people. We have spent real time doing research in reinforcement learning, interpretability, and world models, so we know the work from the inside. Research is slow, technical, and unforgiving. Most of the hours do not go into having ideas, they go into setting up experiments, babysitting training runs, reading results, and deciding what to try next. That loop is the actual bottleneck, and it is a loop. So we asked the obvious question. What if we could automate it?
What it does
AlphaResearch is an autonomous researcher. We use agent harnesses and sandbox environments (w/ root level access) to run research experiments in parallel in a systematic way. You start by chatting with a lead agent that behaves like a principal investigator. It pins down the research goal with you, looks at existing literature, and turns a vague direction into a concrete, testable plan. From there it dispatches a fleet of researcher agents that go off and do the actual work. Each researcher runs its own experiments in its own sandbox, tests its assigned idea, iterates, and reports back with strong, opinionated, evidence-based claims rather than vibes. The PI(Principal Investigator) agent then reconciles what came back and decides what is real. There are two ways to run it. The first is interactive, where you stay in the loop as the PI and steer. The second is fully autonomous. You seed an idea and the platform runs the research loop on its own, round after round, until the PI agent decides it has findings worth keeping. That loop can run for minutes or for days. Every researcher works against a fixed budget and a bounded depth, so the system cannot quietly spawn ten thousand jobs or burn an unbounded bill. Results are not just text either. Researchers produce real training curves, metrics, and experiment dashboards that flow back to the PI as artifacts, so a claim arrives with the evidence attached. Right now we focus on reinforcement learning and machine learning problems, where we can actually train, simulate, and learn from the results inside the system.
How we built it
We built both the PI agent and the researcher agents on a Claude Code agent harness, using skills, subagents, tools, and hooks. The PI agent first researches and reads, then proposes research directions and hands them to the researcher agents as concrete assignments. The piece we are proudest of is not any single agent, it is the seam underneath them. Early on we locked a hard contract between the infrastructure and the agent logic: the schemas for a research plan, the dispatch path that spawns work, and the shared store. Once that seam was frozen, the agent side and the infra side could move independently without breaking each other. This is the only reason a mid-build architecture change did not sink us. For compute, we use cloud sandboxes from Modal, which are virtual machines with root access. This gives each agent room to create files, delete files, and read the context we embed, while keeping it contained away from sensitive data and destructive actions. It also gives us real compute, so a sandbox can run a full training loop, a simulation, or an evaluation as part of the job rather than faking it. Modal is where all of our researcher agents live. For the control plane we use Google Cloud and Redis. Cloud Run hosts our API and the runner loops that drive the main agent, and the main agent itself runs as a job. Redis does a surprising amount of the heavy lifting here. It is our state store, our job queue, our event bus, our budget ledger, and the transcript stream all at once. The frontend subscribes to that event bus over server sent events, so you watch the job tree and the agent feed update live, and you can disconnect and resume a session exactly where you left off. Artifacts that researchers produce, like plots and metrics, get pushed to Google Cloud Storage and handed back to the PI. We persisted all of our cross session agent memory using Redis Agent Memory. As a mobile platform we use Poke to send text messages directly to the main agent for research on the go. Researchers run real experiments inside their sandboxes and log everything to Weights and Biases, and we use Browserbase to capture the live dashboard back into the run, so the PI gets the same visual evidence a human would look at instead of a paragraph of self-reported success. The dispatch path itself is guarded. Before any sandbox spins up, a plan is validated against budget, depth, and safety bounds, so an autonomous system cannot wander off, spawn unbounded work, or blow the whole budget on a single bad idea. We wired observability through Sentry and OpenTelemetry across both the control plane and the sandboxes, so a failing researcher leaves a trace instead of disappearing into a black box. The autonomous loop runs on this exact same infrastructure. It is the chat-agent system with a policy on top that decides, each round, whether to keep going or to stop and report.
Challenges we ran into
The biggest one was observability, and specifically the black box around the sandboxes. Sentry gave us great traces, but we learned quickly that tool calls and reasoning steps are not enough on their own. For research we needed to reason about why an agent took a step and why it failed at a task, not just what it called. Researchers also failed in ways that looked random at first, and our early theories for why were naive. Over time we found the real causes and fixed them one by one. We attacked these with adversarial reviewers that try to refute a finding before we trust it, with deeper tracing into each step, and by hardening the dispatch and ops path so that a bad credential or a stale deploy could not silently take down a run. Then there was distributed reality, which is where a lot of agent demos quietly die. There is no shared filesystem between the control plane and the sandboxes. There are cold starts. There are concurrency races when several researchers run at once. We even had to keep secrets in sync across two separate stores, one for the control plane and one for the sandboxes, and a single mismatch would take the whole run down. Keeping one source of truth across all of these moving parts was a constant fight.
Accomplishments we're proud of
We shipped a fully working end-to-end product in 24 hours. A real conversation turns into a plan, the plan fans out into researcher agents running in separate sandboxes, those agents run actual training runs, and real metrics and dashboards come back to the PI for synthesis. We got recursive sub-agents orchestrated in sandboxes working reliably, with budgets and depth limits so the system is autonomous without being reckless. We survived a significant architecture change mid-build because we had locked the seam first, which felt like the thing was actually paying off in real time. A lot of us went deep on documentation for GCP, Modal, Sentry, Redis, and the Anthropic stack, learned a ton, and came out genuinely excited to show this off after the hackathon.
What we learned
Research is search, and the substrate matters more than the prompt. The hard and valuable part is not the agent's wording. It is the recursive, sandboxed, budget governed machine that lets a swarm of agents run validly in parallel. Build the seam before the intelligence. Locking the contract between infra and agent logic is the only reason a mid-build architecture change did not kill us. Keep a human at depth zero and a verifier in the loop. Autonomy is a slider, not a switch. You earn each notch by making the layer beneath it trustworthy. Budgets are a first-class feature, not an afterthought. An autonomous system without a hard ceiling is just a fast way to spend money and compute. Demos lie, nines don't. Distributed reality, with no shared filesystem, cold starts, and concurrency races, is where autonomous-agent dreams actually live or die.
What's next
Launch an open source version of the product first, and offer a hosted version to enterprises later. Move to Daytona sandboxes with higher performance GPUs so we can run much heavier simulations and more demanding training, well beyond the small RL problems we run today. Spin up thousands of sandboxes with Kubernetes and SkyPilot so a single user can run many more hypotheses and experiments at once, all still directed from one conversation. Broaden past reinforcement learning into other research domains, and give the system memory across runs so it starts to learn what works and stops repeating dead ends.
AlphaResearch
Recursive automated-research platform: a single Claude Agent SDK orchestrator (the "main agent") that the user talks to, which recursively dispatches research sub-agents — each in its own Modal sandbox — to explore strategies in parallel and report summaries back up. State, the event bus, the job queue, and the compute budget all live in Redis; artifacts live in GCS.
Plan & tasks: meta-planning/docs/plan.md, meta-planning/docs/tasks.md; design
rationale: meta-planning/docs/design.md.
Status: cloud backplane (Redis Cloud + GCS + Modal) wired and verified end-to-end
via scripts/smoke_modal.py. Next: full agent loop over Modal, then the live web demo.
Layout
agent/ self-similar run_agent + Claude Agent SDK tools (research-loop layer)
infra/ the LOCKED seam: store (Redis/GCS), schemas, dispatch, registry, modal_app
orchestrator/ FastAPI API (sessions + SSE), depth-0 worker, Modal runner
web/ Next.js chat + live agent-tree dashboard
scripts/ dev harnesses
deploy/ docker-compose.dev.yml, Cloud Run configs
The architecture is split by a stable seam (infra/store.py + infra/dispatch.py
infra/schemas.py): the research-loop layer (agent/) only ever calls that seam, never Redis/GCS/Modal directly — so the loop can be rewritten without touching infra.
Quickstart (local, no cloud)
# 1. deps (Python pinned to 3.12 via uv)
uv sync --extra dev
# 2. local Redis Stack (RedisJSON + Streams)
docker compose -f deploy/docker-compose.dev.yml up -d
# 3. configure
cp .env.example .env # set ANTHROPIC_API_KEY; ALPHA_DISPATCH_BACKEND=local
# 4a. infra-only smoke (no API key needed) — exercises store + dispatch + experiment stub
uv run python scripts/smoke_infra.py
# 4b. full depth-0 agent loop (needs ANTHROPIC_API_KEY)
uv run python scripts/run_depth0.py "Improve PPO sample efficiency on MiniGrid-DoorKey-8x8"
# 5. API + SSE
uv run uvicorn orchestrator.api:app --reload --port 8080
# POST /sessions {"goal": "..."} -> GET /sessions/{id}/stream (SSE)
DISPATCH_BACKEND=local runs the whole tree in-process with synthetic experiment
stubs — fast iteration with only Redis up. Switch to modal once the Modal image is
built and credentials are set.
Configuration: .env vs Modal secrets
Two runtimes, two config sources — they are separate:
.envconfigures processes on your machine (orchestrator/API/worker, andDISPATCH_BACKEND=local). Loaded byinfra/config.py.- The
alpha-secretsModal secret is injected as env vars into the cloud Modal containers (depth ≥ 1 sub-agents / experiments). They never see your local.env.
A few values must exist in both places because each runtime reads its own source:
| value | local .env | Modal alpha-secrets |
|---|---|---|
| Redis URL | ✅ | ✅ |
ANTHROPIC_API_KEY | ✅ | ✅ |
| GCS bucket / creds | ✅ | ✅ |
| Modal token | — (in ~/.modal.toml) | — (ambient in Modal) |
When
DISPATCH_BACKEND=modal, set the Redis URL to your Redis Cloud endpoint (rediss://…) in both places — neverlocalhost. The local orchestrator and the cloud sandboxes must share the same Redis. For pure local dev (DISPATCH_BACKEND=local) you don't need the Modal secret at all and.envkeepslocalhost.
Modal setup (only for DISPATCH_BACKEND=modal)
modal token new # authenticate (writes ~/.modal.toml)
modal secret create alpha-secrets \
ALPHA_REDIS_URL="rediss://default:<password>@<host>:<port>" \
ANTHROPIC_API_KEY="sk-ant-..." \
ALPHA_GCS_BUCKET="alpha-artifacts" \
ALPHA_DISPATCH_BACKEND="modal"
modal deploy infra/modal_app.py # makes run_job addressable (incl. nested spawn)
The secret name must be alpha-secrets (referenced in infra/modal_app.py). GCS uploads
need a service-account credential — use the Modal dashboard's Google Cloud secret template,
or leave ALPHA_GCS_BUCKET unset to fall back to local-disk artifacts while validating the
Modal compute path first.
Frontend (web/)
The Next.js app talks to the FastAPI API over REST + SSE. For local development you can run the API in local-sim mode (a scripted research run per session, no cloud credentials) and point the web app at it:
# Terminal 1 — API in local-sim mode (no Cloud Run/Modal, no ANTHROPIC_API_KEY)
ALPHA_RUNNER_ENABLED=false ALPHA_LOCAL_SIM=true \
uv run uvicorn orchestrator.api:app --port 8080
# Terminal 2 — Next.js dev server (http://localhost:3000)
cd web && npm run dev
Copy web/.env.example to web/.env.local first. With Clerk left unset the web app
runs keyless as a fixed "demo" user (see web/lib/auth-config.ts); the API similarly
stays in open dev mode while ALPHA_CLERK_JWKS_URL is unset.
Production deploy
Deploy the API (Cloud Run / your host of choice), then configure the three boundaries — the web → API URL, Clerk auth on both sides, and CORS:
-
Point the web app at the deployed API. Set
NEXT_PUBLIC_API_URLin the web environment to the deployed API origin (e.g.https://api.example.com). It is inlined at build time (web/lib/types.tsreadsprocess.env.NEXT_PUBLIC_API_URL), so set it before building the frontend. -
Enable Clerk. Without these the app runs as the open "demo" user, so set them in production:
- Web:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY+CLERK_SECRET_KEY(from the Clerk dashboard). Setting the publishable key flipsCLERK_ENABLEDon, requiring sign-in and sending a verified token to the API. - Backend:
ALPHA_CLERK_JWKS_URL(e.g.https://<subdomain>.clerk.accounts.dev/.well-known/jwks.json) andALPHA_CLERK_ISSUER(required whenever the JWKS URL is set — the API fails fast otherwise).ALPHA_CLERK_AUDIENCEis optional. Runuv sync --extra authso the JWT-verification deps are present.
- Web:
-
Set CORS to the deployed web origin. The API's allowed browser origins are env-driven via
ALPHA_CORS_ALLOW_ORIGINS(backssettings.cors_allow_originsininfra/config.py; defaults to["http://localhost:3000"]). It is parsed as a JSON list, so set it to your deployed web origin(s):ALPHA_CORS_ALLOW_ORIGINS='["https://app.example.com"]'
Analysis
View
Metric
- 73
- 55
- 55
- 22
- 9
- 3
- 1
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- FastAPIIn code
- HTMLIn code
- Next.jsIn code
- PythonIn code
- PyTorchIn code
- ReactIn code
- RedisIn code
- Tailwind CSSIn code
- TypeScriptIn code
- AnthropicClaimed
10 of 11 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
- Claude CodeConfig · Commits
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
1.4 MB
Source files
265
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
JasonLai150/AlphaResearch
290 files · 1.9 MB · @ 4464332
Structure
Interface
50 files · 17%Screens, components and styles rendered to the user.
Application logic
59 files · 20%Domain rules, services and shared utilities.
+3 more
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- Markdown44%
- Python34%
- TypeScript19%
- Shell2%
- HTML1%
- CSS0%
- Other (1)0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
web/package.json
npm · 38- @clerk/nextjs
- @radix-ui/react-avatar
- @radix-ui/react-dialog
- @radix-ui/react-scroll-area
- @radix-ui/react-separator
- @radix-ui/react-slot
- @radix-ui/react-tooltip
- class-variance-authority
- clsx
- d3-force
- geist
- lucide-react
- next
- react
- react-dom
- recharts
- sonner
- tailwind-merge
- +20 more
pyproject.toml
pypi · 28- claude-agent-sdk
- fastapi
- google-cloud-logging
- google-cloud-run
- google-cloud-storage
- httpx
- modal
- orjson
- pydantic
- pydantic-settings
- redis
- sse-starlette
- tenacity
- uvicorn[standard]
- +14 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Feature verification
Artifacts (metrics, training curves, dashboards) flow back to the PI via GCSVerified
Researchers produce real training curves, metrics, and dashboards that flow back to the PI as artifacts
Claimed on Devposthigh confidencerunner/gcs_uploader.py:29— upload_artifacts() ships a sub-agent's artifact dir to GCS and records ArtifactRefs in Redisagent/main-agent/scripts/read_artifacts.py— Main agent reads a child's artifacts (gs:// urls) back for synthesis
Autonomous multi-round research loop with a stop policyVerified
A fully autonomous mode where you seed an idea and the platform runs the research loop round after round until the PI decides it has findings worth keeping
Claimed on Devposthigh confidenceinfra/loop_policy.py:49— decide() implements stop/continue logic based on stop_requested, budget, max_rounds, goal_metric, and plateau detectionagent/main-agent/CLAUDE.md— Describes 'Autonomous loop rounds' where the agent does one round and reports via report_round.py, and the runner owns the stop policy
Budget and depth-bounded dispatch guardrailsVerified
Every researcher works against a fixed budget and bounded depth so the system cannot spawn unbounded work or blow the budget
Claimed on Devposthigh confidenceinfra/dispatch.py:61— Raises DepthExceeded/FanoutExceeded/BudgetExceeded before a child job is created, using atomic Redis fanout claim and budget decrementtests/test_research_plan_guardrails.py— Test file dedicated to guardrail enforcement
Chat-based PI agent that turns a goal into a research planVerified
You start by chatting with a lead agent that behaves like a principal investigator, pins down the goal, looks at literature, and turns it into a concrete testable plan
Claimed on Devposthigh confidenceagent/main-agent/CLAUDE.md— Defines the main agent's workflow: probe user, use research skill to produce a ResearchPlan JSONagent/main-agent/skills/research/SKILL.md:71— Phase 1 does broad web search/literature reading before proposing a ResearchPlan with frozen scaffold and diverse ideas
Cloud Run hosts the API and runs the main agent as a jobVerified
Cloud Run hosts our API and the runner loops that drive the main agent, and the main agent itself runs as a job
Claimed on Devposthigh confidencerunner/cloud_run_client.py:38— trigger_main_agent triggers a Cloud Run Job execution per chat for the main agentdeploy/api.Dockerfile— Dockerfile for deploying the API, consistent with Cloud Run hosting
Dispatch of parallel researcher sub-agents into isolated sandboxesVerified
The PI dispatches a fleet of researcher agents that each run in their own sandbox
Claimed on Devposthigh confidenceinfra/dispatch.py:41— dispatch() creates a child Job and launches it via the local or modal backendagent/main-agent/scripts/dispatch_subagent.py— Main agent invokes this script once per idea to fan out sub-agent containersagent/sub-agent/CLAUDE.md:1— Sub-agent runs in its own isolated container responsible for one research idea
Dispatch path validated against budget/depth/safety bounds before sandboxes spin upVerified
Before any sandbox spins up, a plan is validated against budget, depth, and safety bounds
Claimed on Devposthigh confidenceagent/main-agent/skills/research/SKILL.md:61— PreToolUse hook re-validates the plan schema/diversity rules before dispatch_subagent.py runsinfra/dispatch.py:61— Depth/fanout/budget checks happen inside dispatch() before a job is created and launched
Frontend live job-tree dashboard and resumable sessions over SSEVerified
The frontend subscribes to the event bus over SSE so you watch the job tree and agent feed update live, and can disconnect and resume a session exactly where you left off
Claimed on Devposthigh confidenceorchestrator/api.py:209— SSE endpoint returns EventSourceResponse and supports resuming from a real last-event idweb/components/agent-tree.tsx:1— Renders a tidy-tree visualization of the agent/job graph with live status colors
Modal cloud sandboxes with root access for computeVerified
We use cloud sandboxes from Modal, which are virtual machines with root access, to run researcher agents
Claimed on Devposthigh confidenceinfra/modal_app.py:57— Defines a modal.App with functions running the sub-agent/experiment imagesREADME.md— Documents 'modal deploy infra/modal_app.py' and the alpha-secrets Modal secret for sandbox credentials
Redis as state store, job queue, event bus, and budget ledgerVerified
State, the event bus, the job queue, and the compute budget all live in Redis
Claimed on readmehigh confidenceinfra/store.py:345— emit_event XADDs to a Redis Stream used as the session event businfra/store.py:316— decr_budget implements the budget ledger in Redisinfra/store.py:388— enqueue_session/enqueue_dispatch use Redis Streams as job queues
Researcher agents run real training experiments and report evidence-based resultsVerified
Each researcher runs its own experiments, iterates, and reports strong evidence-based claims rather than vibes
Claimed on Devposthigh confidenceagent/sub-agent/scripts/train_ppo.py— Prebaked PPO trainer that runs baseline + intervention and writes result.json/metrics.json/training_curves.pngagent/sub-agent/CLAUDE.md:104— Instructs the sub-agent to report honest negative results and never fake result.json
Adversarial reviewers that try to refute a finding before it's trustedCode-supported
We attacked failures with adversarial reviewers that try to refute a finding before we trust it
Claimed on Devpostmedium confidenceagent/main-agent/skills/research/SKILL.md:3— Describes an 'adversarial review pass' that trims candidate ideas before dispatch, but this is a prompted LLM step, not a separate enforced reviewer agent/service
Browserbase captures the live W&B dashboard back into the runClaimed only
We use Browserbase to capture the live dashboard back into the run so the PI gets the same visual evidence a human would look at
Claimed on Devposthigh confidencePoke mobile texting into the main agentClaimed only
As a mobile platform we use Poke to send text messages directly to the main agent for research on the go
Claimed on Devposthigh confidenceRedis Agent Memory for cross-session agent memoryClaimed only
We persisted all of our cross session agent memory using Redis Agent Memory
Claimed on Devposthigh confidenceSentry and OpenTelemetry observability across control plane and sandboxesClaimed only
We wired observability through Sentry and OpenTelemetry across both the control plane and the sandboxes
Claimed on Devposthigh confidenceWeights & Biases experiment loggingClaimed only
Researchers run real experiments inside their sandboxes and log everything to Weights and Biases
Claimed on Devposthigh confidence
An AI agent derived these features from the project’s Devpost page and readme, then searched the code for each one. Verified features are backed by cited code; claimed-only features had no supporting code, which is not by itself proof a feature is missing.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.