The control plane for autonomous AI development.
Not assisted. Autonomous.
Quickstart · Why Gigi · Features · Architecture · Configuration · Security · License
Caution
Gigi has full shell access and pre-authenticated Gitea. Never expose Gigi to the public internet. Bind to localhost or a private network only. See Security for details.
Note
Gigi is in pre-alpha. It's battle-tested (Gigi's own code is developed with Gigi), but not perfect yet. We're looking for volunteers willing to take it for a spin. See Security for deployment guidelines.
IDEs and CLIs were designed for humans — a person typing code, reading diffs, clicking buttons. When AI entered the picture, we bolted copilots onto these human-centric tools and called it "AI-assisted development."
But autonomous development is a different game. When an AI agent works independently — reading issues, writing code, creating PRs, verifying its own output — it doesn't need syntax highlighting or keybindings. It needs task tracking, completion enforcement, real-time visibility, and budget control.
Running autonomous agents through a terminal is like managing a factory floor through a typewriter. You can make it work, but you're burning tokens, losing context, and flying blind.
Gigi is the control plane for autonomous AI development. Instead of watching an agent scroll through a terminal, you get:
- A Kanban board that updates in real-time as the agent moves through tasks
- Task enforcement that prevents the agent from stopping mid-work — enforced by code, not prompts
- Conversations linked to issues — every webhook, every PR, every comment routed to the right thread
- A shared browser the agent uses to debug live websites, inspect the DOM, read console errors, run scripts, and trigger events — powered by Google Chrome DevTools Protocol (MCP)
- Token and cost tracking so you know exactly what you're spending
- Always with you — Telegram integration means your agent is reachable from anywhere, on any device
- Self-extension — the agent evolves its own capabilities through PRs to its own repo
Self-hosted. Open source. Your hardware, your data, your agent.
Gigi integrates with Gitea project boards. Issues flow through columns — Ready → In Progress → Review → Done — and the agent updates status labels automatically as it works. The board updates in real-time via WebSocket.
No more "did the agent finish?" Just look at the board.
The biggest problem with autonomous agents: they stop mid-task. They write code but don't push. They push but don't create a PR. They create a PR but don't notify you.
Gigi solves this with a state machine enforcer that tracks every task through a completion loop:
Code Changed? → Branch Pushed? → PR Created? → Notification Sent? → ✅ Done
At each step, if the agent stalls, the enforcer injects a continuation prompt automatically. The agent cannot go idle with unfinished work. This is enforced by code, not by system prompt suggestions.
Every issue and PR gets its own persistent conversation. Gitea webhooks automatically route events to the right thread:
| Event | What Happens |
|---|---|
| Issue opened | Conversation created, agent has full context |
| PR merged | Conversation updated, linked issues closed |
@gigi in a comment |
Agent responds in the linked conversation |
| Push event | Commit summary attached to repo conversation |
| Pipeline failure | Agent notified, can auto-investigate |
You chat with the agent about a specific issue, and all context — code changes, reviews, deployments — stays linked in one place.
Gigi runs a persistent Chrome instance with full DevTools Protocol access via the Chrome DevTools MCP. The agent can:
- Navigate pages and inspect the live DOM
- Read
console.errorand other console output in real-time - Execute JavaScript in the page context — trigger events, extract data, manipulate state
- Take screenshots and DOM snapshots for visual verification
- Monitor network requests — inspect headers, payloads, and response bodies
- Click, fill forms, and interact with page elements programmatically
The agent debugs live websites — including its own UI. You watch it happen in the Browser tab. This isn't a simulated environment; it's a real Chrome instance the agent controls through the same protocol your browser DevTools use.
Every message tracks input/output tokens and estimated cost. Per-conversation and aggregate views show exactly where your budget is going. No surprise bills from runaway agent loops.
Gigi isn't trapped in a browser tab. With Telegram integration, your agent is always running, always reachable:
- Get notified when tasks complete, PRs are created, or issues need attention
- Send instructions to your agent from your phone, on the train, from bed — anywhere
- Full two-way chat — same agent, same context, different channel
- Cross-channel routing — start a conversation on the web, continue it on Telegram
Your autonomous development pipeline doesn't stop when you close your laptop.
Gigi's source code lives in a Gitea repo that the agent itself can modify:
- Identifies a missing capability or bug
- Clones its own repo, creates a feature branch
- Implements the change
- Creates a PR for you to review
- Notifies you via Telegram or Web UI
After you merge, CI/CD deploys the update automatically. The agent evolves itself — new tools, prompt improvements, UI features, bug fixes.
┌──────────────────────────────────────────────────────────┐
│ Gigi Instance │
│ │
│ ┌────────────┐ ┌──────────┐ ┌────────────────────┐ │
│ │ Gigi │ │ Gitea │ │ PostgreSQL │ │
│ │ Agent │ │ (forge) │ │ (state + history) │ │
│ └─────┬──────┘ └──────────┘ └────────────────────┘ │
│ │ │
│ ├── Claude Agent SDK (session persistence) │
│ ├── MCP tools (gitea, telegram, browser, ask) │
│ ├── Task enforcer (state machine) │
│ ├── Webhook router (events → conversations) │
│ │ │
│ ├──► Chrome (DevTools Protocol via MCP) │
│ │ ↕ Live browser visible in UI │
│ │ │
│ └──► Svelte 5 Web UI │
│ ├── Kanban board (real-time) │
│ ├── Chat (conversations + tool output) │
│ ├── Gitea views (issues, PRs, code) │
│ └── Browser tab (live Chrome stream) │
│ │
│ ◄──► Telegram (two-way, always reachable) │
└──────────────────────────────────────────────────────────┘
+-----------------------------------------------------------+
| A: Kanban Board (full / compact / hidden) |
+----------+------------------------------------------------+
| B: Chat | C: Filters / View Tabs |
| Sidebar +------------------------------------------------+
| | D: Main View (Overview / Gitea / Browser) |
| | |
| | +------------------------------------------+ |
| | | F: Chat Overlay (expand / compact / hide) | |
+----------+--+------------------------------------------+--+
| Component | Technology |
|---|---|
| Runtime | Node.js 22 (TypeScript, strict mode) |
| HTTP | Hono |
| Agent | Claude Agent SDK + MCP |
| Frontend | Svelte 5 + Vite |
| Validation | Zod |
| Database | PostgreSQL |
| Browser | Chrome + DevTools Protocol MCP |
| Messaging | grammY (Telegram) |
| Container | All-In-One (AIO) — Gigi + Gitea + Chrome + noVNC |
| Deployment | Docker Swarm, Gitea Actions CI/CD |
lib/
├── core/ # Agent loop, router, store, events, enforcer
├── api/ # HTTP routes (Hono), webhooks, Telegram, Gitea proxy
├── api-gitea/ # Typed Gitea API client
├── domain/ # Business logic (issues, projects, setup wizard)
├── tools/ # MCP tool servers (gitea, telegram, ask-user, browser)
└── backup/ # Repository backup & mirror system
web/app/
├── components/ # Svelte 5 UI (AppShell, Kanban, chat, panels)
├── lib/stores/ # Reactive state (chat, panels, navigation, kanban)
├── lib/services/ # WebSocket client, API layer
└── lib/utils/ # Markdown, formatting, link handling
src/
├── index.ts # Server bootstrap: HTTP + WS + Telegram + enforcer
└── server.ts # WebSocket server management
Gigi uses an All-In-One (AIO) image that bundles the agent, Gitea, Chrome, and noVNC into a single container. You only need PostgreSQL alongside it.
git clone https://github.com/user/gigi.git
cd gigi
cp .env.example .env
# Edit .env — set DATABASE_URL
docker compose up -dOpen http://localhost:3100 — the setup wizard walks you through connecting your Anthropic API key and (optionally) Telegram.
Important
Keep Gigi bound to localhost or a private network. See Security before exposing it to any external network.
What runs inside the AIO container:
| Component | Description |
|---|---|
| Gigi Agent | AI agent + real-time web UI |
| Gitea | Git forge — repos, issues, PRs, project boards |
| Chrome | Headless browser with DevTools Protocol for automation |
| noVNC | Browser viewer — watch the agent interact with pages |
You need a PostgreSQL instance (external or in the same compose). See Configuration for details.
./dev.sh # Start AIO infra + dev servers with HMR
./dev.sh --fresh # Wipe state and start fresh (shows onboarding)Configuration is stored in PostgreSQL and managed via the web UI setup wizard at /setup.
| Service | Purpose |
|---|---|
| PostgreSQL | Conversations, messages, config, task state |
| Anthropic API | Claude models for the agent |
Gitea and Chrome are bundled inside the AIO container — no separate setup needed.
| Service | Purpose |
|---|---|
| Telegram Bot | Mobile notifications and two-way chat from anywhere |
| Backup Gitea | Repository mirroring to secondary instance |
| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string | required |
PORT |
HTTP server port | 3000 |
ADMIN_USER |
Gitea admin username (created on first boot) | admin |
ADMIN_PASSWORD |
Gitea admin password | admin |
ORG_NAME |
Gitea organization name | idea |
GIGI_INSTANCE_URL |
External URL for Gitea redirect config | http://localhost:3000 |
GITEA_URL |
Use an external Gitea instead of internal | — |
CHROME_CDP_URL |
Use an external Chrome instead of internal | — |
TELEGRAM_BOT_TOKEN |
Telegram bot token for mobile access | — |
The agent operates through these tool servers:
| Tool | Capabilities |
|---|---|
| gitea | Create repos, manage issues/PRs, update labels, post comments |
| ask_user | Ask the operator a question via web UI (blocks until answered) |
| telegram_send | Send Markdown-formatted notifications to Telegram |
| Chrome DevTools | Navigate, screenshot, evaluate JS, click, fill, inspect network, read console |
| IDE / CLI AI Assistants | Gigi | |
|---|---|---|
| Designed for | Human-assisted coding | Autonomous agent operations |
| Visibility | Terminal scroll | Kanban + live browser + linked chats |
| Task completion | Hope the agent finishes | State machine enforcement |
| Context | Lost between sessions | Persistent, linked to issues/PRs |
| Cost awareness | Check your bill later | Real-time token tracking |
| Browser debugging | You open DevTools manually | Agent runs Chrome DevTools autonomously |
| Availability | Only when your IDE is open | Always on — web + Telegram |
| Self-improvement | You update the config | Agent PRs its own repo |
| Hosting | Cloud vendor | Self-hosted, your hardware |
Automated via Gitea Actions (.gitea/workflows/build.yml):
- Build Docker images (ARM64 + AMD64)
- Push to Gitea container registry
- Deploy stack via
docker stack deploy - Update reverse proxy config
Gigi is designed for trusted, private environments. It trades sandboxing for autonomy — which is the point — but this means you must secure the perimeter yourself.
| Risk | Detail |
|---|---|
| Unrestricted shell | The agent runs with dangerouslySkipPermissions so it can execute any command without confirmation prompts. This is required for autonomous operation but means a misconfigured prompt or malicious input could cause damage. |
| Pre-authenticated Gitea | The Gitea proxy injects X-WEBAUTH-USER automatically. There is no login screen — anyone who can reach the UI has full access to all repositories. |
| Credentials in database | API tokens for Anthropic, Gitea, and Telegram are stored in PostgreSQL. Protect your database connection and backups accordingly. |
| Browser automation | The agent controls a real Chrome instance. It can navigate to any URL, execute JavaScript, and interact with pages — including authenticated sessions if cookies are present. |
- Bind to localhost or a private network interface — never
0.0.0.0on a public-facing machine. - Use a VPN or SSH tunnel if you need remote access.
- Run in Docker with appropriate network isolation (the default
docker composesetup does this). - Restrict database access — don't expose PostgreSQL to the network.
- Review agent activity — check the conversation history and Gitea audit logs periodically.
- Set a cost budget — use Gigi's built-in token tracking to cap spending and prevent runaway loops.
If you discover a security issue, please open a private issue or contact the maintainers directly rather than posting publicly.
AGPL-3.0