Gust Deck

Gust Deck is a lightweight operator dashboard and Telegram-driven automation service for running coding jobs against GitHub issues. A user can start a job from Telegram or the web dashboard, the worker clones the target repository into a dedicated worktree, runs a coding agent against the issue, pushes a branch, opens a pull request, and streams progress back to both Telegram and the web UI.

What It Does

• Starts issue-driven coding jobs from Telegram with /run <repo> #<issue>
• Starts coding sessions from the web dashboard
• Tracks job state in a local SQLite database
• Queues and processes jobs with BullMQ + Redis
• Streams curated agent activity to a React dashboard over SSE
• Supports follow-up instructions from Telegram replies or the dashboard
• Creates branches, commits, pushes, and pull requests through the GitHub CLI
• Supports Claude and Codex backends behind a shared agent runtime
• Uses passwordless email login for the dashboard via Resend

Architecture

The app runs as a Bun server with two major surfaces:

• src/server: Hono API, Telegram webhook handling, auth routes, BullMQ worker, agent runtime, git/GitHub orchestration, and SQLite access
• src/client: Vite + React dashboard for jobs, job detail streaming, repo settings, session creation, and email login

Core services:

• Redis: queue backend and pub/sub for live job streams
• SQLite: persistent job, message, repo, and Telegram message-link storage in data/pulse.db
• GitHub CLI: repo cloning, issue fetch, auth verification, and PR creation
• src/server/agent: shared runtime layer with Agent, ExecutionContext, GitRuntime, response formatting, and provider backends
• Claude Code SDK: Claude-backed autonomous code editing inside per-job git worktrees
• Codex SDK: Codex-backed autonomous code editing inside per-job git worktrees
• Telegram Bot API: command intake and job status notifications
• Resend: magic-link email auth for the dashboard

Requirements

Before running the project, make sure these are available on the machine:

• Bun
• GitHub CLI authenticated with access to the target repos
• Redis
• A Telegram bot token and the allowed chat ID
• A Resend API key for dashboard sign-in emails in production
• Claude Code SDK access/auth on the machine that runs jobs when using AGENT_PROVIDER=claude
• Codex access available on the machine that runs jobs when using AGENT_PROVIDER=codex

Environment Variables

Create a .env file in the project root.

| Variable | Required | Purpose | | --- | --- | --- | | TELEGRAM_TOKEN | Yes | Telegram bot token | | TELEGRAM_CHAT_ID | Yes | Only this Telegram chat can control the agent | | TELEGRAM_WEBHOOK_SECRET | Yes | Secret checked on incoming Telegram webhooks | | REDIS_URL | No | Redis connection string, defaults to redis://127.0.0.1:6379 | | SESSION_SECRET | Yes | Session secret placeholder for auth-related config | | DASHBOARD_URL | No | Public dashboard base URL used in login emails and Telegram links; defaults to http://localhost:5173 in local dev | | RESEND_API_KEY | No | Resend API key for magic-link sign-in; required in production, optional in local dev | | AUTH_FROM_EMAIL | No | Sender for auth emails, defaults to Gust Deck <[email protected]> | | PORT | No | Bun server port, defaults to 3000 | | REPOS_ROOT | No | Directory for persistent clones and worktrees, defaults to <project>/repos | | AGENT_PROVIDER | No | Coding backend to use, claude by default, or codex | | CODEX_EXECUTABLE | No | Override the Codex binary path used by the Codex SDK |

Notes:

• .env.example includes the main runtime variables, including the agent backend selection.
• DASHBOARD_URL should point at the dashboard origin users will actually open.
• In local development, DASHBOARD_URL=http://localhost:5173 works with the Vite proxy.
• In local development, if RESEND_API_KEY is not set, the login screen shows a direct magic link instead of sending an email.

Local Development

1. Install dependencies:

   bun install

2. Start Redis:

   docker compose up -d

   bun run dev:server also pulls, starts, and waits for the Docker Redis service automatically.

3. Authenticate GitHub CLI:

   gh auth login

4. Add your .env file.

5. Start the app:

   bun run dev

This starts:

• API/worker server on http://localhost:3000
• Vite dashboard on http://localhost:5173

Vite proxies /api/* requests to the Bun server during development.

Production Run

Build the client bundle:

bun run build

Start the server:

bun run start

In production, the Bun server serves the built SPA from dist/ and exposes the API from the same process.

Telegram Setup

Configure your Telegram bot webhook to point to:

POST /api/telegram

The request must include the same secret token as TELEGRAM_WEBHOOK_SECRET in the x-telegram-bot-api-secret-token header. The bot ignores messages from chats other than TELEGRAM_CHAT_ID.

Supported commands:

• /run <repo> #<issue>: queue a job for a configured repo shortcut
• /status: list active jobs
• /focus [jobId|#issue]: show or set the active job for free-text follow-ups
• /cancel <jobId>: mark a job as failed/cancelled
• /health: check Redis, SQLite, and GitHub CLI availability
• /help: show command help

Free-text Telegram messages are treated as follow-up instructions when Gust Deck can resolve the active job from:

• a reply to a linked bot message
• the current /focus
• the only running or queued job

Dashboard

The React dashboard provides:

• Jobs: list all jobs by status and start a new coding session
• Job detail: live message stream, summary/error panels, PR link, and follow-up form
• Settings: manage repositories available to Telegram via short names
• Login: email magic-link sign-in

Important API routes:

• POST /api/auth/request
• GET /api/auth/verify
• POST /api/auth/logout
• GET /api/repos
• POST /api/repos
• DELETE /api/repos/:id
• GET /api/jobs
• POST /api/jobs
• GET /api/jobs/:id
• GET /api/jobs/:id/stream
• POST /api/jobs/:id/reply
• POST /api/telegram

Job Lifecycle

When a user starts a job:

1. Gust Deck resolves the repository from the configured short name or selected dashboard repo.
2. The server fetches the GitHub issue via gh issue view.
3. A persistent clone is created if needed under REPOS_ROOT.
4. A fresh git worktree is created for the job branch.
5. The configured coding backend runs against the issue prompt inside that worktree.
6. Agent output is normalized, formatted, and stored in SQLite.
7. Curated messages are published to Redis and streamed to the dashboard.
8. All changes are committed and pushed with Git.
9. A pull request is opened with gh pr create.
10. Telegram receives success or failure status plus a dashboard or PR link when a chat is configured.

Data and State

• SQLite database: data/pulse.db
• Redis: queue state and pub/sub streams
• Persistent repo clones: REPOS_ROOT/<org>/<repo>
• Per-job worktrees: REPOS_ROOT/<org>/<repo>--worktrees/...

Useful Scripts

• bun run dev: run API/worker and Vite UI together
• bun run dev:server: run only the Bun server with watch mode
• bun run dev:ui: run only the Vite dashboard
• bun run build: build the client app to dist/
• bun run start: start the Bun server
• bun run typecheck: run TypeScript type checking

Project Structure

src/
  client/
    components/
    pages/
    main.tsx
  server/
    agent/
    routes/
    services/
    config.ts
    db.ts
    index.ts
data/
  pulse.db
docker-compose.yml

Current Assumptions and Caveats

• The server process also instantiates the BullMQ worker, so API and worker run together.
• PR creation currently targets the main branch.
• GitHub auth is validated via gh auth status at startup.
• Job execution assumes the machine has the tooling and permissions needed to clone, edit, commit, and push repository changes.
• The Claude backend currently uses the Claude Code SDK, while the Codex backend uses the Codex SDK, which manages Codex execution and streaming internally.