Shadow is an open-source background coding agent that understands, navigates, and edits real repositories, then graduates those edits into reviewable pull requests. It brings together a Next.js frontend, a Node.js server orchestrator, a file-ops sidecar, and an isolated execution substrate to make agents useful on live code, not just in a chat box. It's a direct competitor to the likes of the Gemini CLI, Claude Code and Github CoPilot Issues Agent. With competition like this, Shadow has a long road to proving its practicality for dev teams!
The project supports a local developer mode and a deployment-grade remote mode powered by Kata Containers and the QEMU hypervisor for hardware-assisted isolation. Data flows through Prisma to PostgreSQL, and optional semantic search is available via Pinecone to help the agent find relevant context across large trees ((The Kata Containers Project, 2025); (Vercel, 2025); (Prisma, 2025)).
The problem and the shape of a solution
Most AI coding helpers stop at suggestion and leave humans to reconcile diffs, move files, and run checks. Shadow tackles the harder end-to-end loop: read the repository precisely, propose edits in place, validate with local tooling, and open a pull request tied to the branch you select. That adds two non-negotiables: observability (logs, diffs, progress) and safety (command validation and isolation). Shadow embeds both into the core workflow with a real-time web UI and an execution layer that can run on your machine or inside a micro-VM.
Why I like it
Shadow treats GitHub as the source of truth and PRs as the artifact. The agent's tools map cleanly to what developers do: read_file with line ranges, grep_search, safe terminal commands, and a memory system for repo-specific context. There is little magic and lots of pragmatic plumbing, which makes it easier to trust and adopt incrementally. The optional Pinecone integration is a nice bonus for very large codebases when simple grep starts to creak ((Pinecone, 2025)).
Key features that matter
- End-to-end stack in TypeScript: chat UI, orchestrator, sidecar, and DB-backed task state.
- Local and remote modes: direct filesystem execution locally; Kata/QEMU isolation for multi-tenant or production deployments.
- GitHub-native workflow: branch selection and AI-authored commits culminating in a PR.
- Purpose-built tools: file operations, regex search, semantic retrieval, and a guarded terminal.
- Monorepo ergonomics: shared TypeScript, ESLint, and Prisma packages for consistency.
Under the hood
The repository is a monorepo with clearly scoped apps and packages. The frontend in apps/frontend is a Next.js app that streams messages and logs in real time. The server in apps/server integrates multiple LLM providers (Anthropic, OpenAI, OpenRouter) and streams events over WebSockets. A narrow REST sidecar in apps/sidecar exposes safe file operations within the chosen execution boundary. Shared types live in packages/types; the Prisma schema and client are in packages/db; and security utilities for command validation sit in packages/command-security.
Mode selection is environment-driven. In local mode, the agent works inside a designated workspace on your machine with strict path and command validation. In remote mode, it runs inside a micro-VM via Kata Containers with QEMU, gaining hardware-level isolation while keeping container-like workflows ((The Kata Containers Project, 2025)).
Setup in practice
The README outlines a straight path: copy env templates, create a local PostgreSQL database, set DATABASE_URL, generate the Prisma client, push schema, and start the dev servers. You can also use the setup-script.sh helper to populate environment variables across packages. With a GitHub personal access token, the repo selector works immediately in local mode ((Dey et al., 2025)).
# apps/server/.env (local mode)
DATABASE_URL="postgres://postgres:@127.0.0.1:5432/shadow_dev"
BETTER_AUTH_SECRET="dev-secret"
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
NODE_ENV=development
AGENT_MODE=local
# apps/frontend/.env.local
NEXT_PUBLIC_SERVER_URL=http://localhost:4000
NEXT_PUBLIC_VERCEL_ENV=development
Where it fits
Shadow is a fit for teams that want an agent to prepare real changes under supervision: refactors across a codebase, small bug fixes that require touching many files, or tedious migrations like updating an HTTP client or lint rules. Local mode suits solo developers and small teams; remote mode enables shared clusters or multi-tenant setups with stronger isolation boundaries.
Community and contribution
The project is actively developed with a clear Contributing section: fork, branch, implement with strict types, test both execution modes, then open a PR. Open issues are tracked under issues, and the authors link public profiles for discussion. The codebase favors explicitness and documentation over hidden behavior, which lowers the barrier for first-time contributors.
Usage and license
Shadow is available under the MIT License, permitting use, copy, modification, distribution, and sublicensing with attribution and without warranty. In short: it is permissive and commercial-friendly, with the usual as-is disclaimer. See the LICENSE for the exact terms ((Open Source Initiative, 2025)).
Impact and what comes next
By anchoring on PRs and isolation, Shadow nudges the field from code generation toward code contribution. It can plug into existing CI, scale from laptop to cluster, and pick up semantic search when repositories get large. Expect integrations to grow (more LLMs, richer search, deeper GitHub automation) and deployment recipes to expand for different Kubernetes environments. The open-source model invites experimentation and reuse across internal developer platforms.
About the team and site
Shadow is developed by Ishaan Dey with collaborators Rajan Agarwal and Elijah Kurien. The repository credits shadowrealm.ai and links to author profiles for context and updates ((Dey, 2025)).
Closing
If you want an agent that can actually land changes, not just suggest them, Shadow is worth a look. Start in apps/frontend, apps/server, and apps/sidecar, wire up your env files, and run it locally. When you are ready to share, flip to remote mode and keep the same development model with stronger isolation.
Shadow: An Open Agent That Codes in the Background