Common questions about setting up, running, and customizing Last Light.
Three things:
claude login)See the Get Started guide for step-by-step instructions.
Last Light uses Claude via the Claude Agent SDK. The default model is claude-sonnet-4-6, configurable via the CLAUDE_MODEL environment variable.
Locally, the Agent SDK uses your Claude Code subscription — no separate API key needed. For production, set ANTHROPIC_API_KEY in .env.
Not yet tested, but it should work with GitHub Enterprise Cloud since it uses the same API. GitHub Enterprise Server (self-hosted) would need base URL configuration in the MCP server — contributions welcome.
Last Light authenticates as a GitHub App, not a personal account. It generates short-lived installation tokens (expire in ~1 hour) using your App's private key. Every action — comments, labels, PR reviews — shows up as coming from the bot, not you.
The MCP server handles token generation and refresh automatically. For git operations inside sandboxes, a credential file is synced before each command.
Webhooks react in real-time — GitHub sends events (issue opened, PR created, comment posted) to your endpoint, and the agent handles them immediately. Requires a publicly reachable URL.
Cron polls on a schedule — the agent checks for new issues, PRs, and stale items periodically (e.g. every 15 minutes). No public URL needed, but responses are delayed.
Use one or the other — not both. Webhooks are better for responsive repos; cron is simpler to deploy.
Yes. When a maintainer @mentions the bot on an issue, it clones the repo into an isolated Docker sandbox, reads the code, makes changes, runs tests, and opens a PR. It's not magic — it works best for well-scoped issues with clear descriptions.
The bot always links back to the original issue and posts validation results so you can review before merging.
It does nothing. Silence is built into the design — the agent only acts on events it has explicit rules for. Unknown event types, ambiguous requests, and bot-generated events are all ignored. For build requests, if it can't push code, it posts a detailed comment explaining what it tried and what needs human attention.
Sandbox sessions are agent runs that executed inside a Docker sandbox — triage, PR review, build, health report, anything driven by a YAML workflow. They are stored as Agent SDK JSONL files on disk and listed on the dashboard's Sandbox Sessions tab.
Chat sessions are conversations from Slack threads. They run the in-process chat skill (not sandboxed) so replies are low-latency, and the harness resumes the same Agent SDK session on every turn of a given Slack thread. Every turn is persisted to SQLite (executions table) and one thread becomes one growing, coherent JSONL. They live on the dashboard's Chat Sessions tab.
In short: sandbox sessions are one-shot workflow runs; chat sessions are multi-turn conversations glued to a Slack thread.
A workflow phase can declare approval_gate: post_architect (or any other gate name). If that gate is enabled via the APPROVAL_GATES env var, the runner pauses after that phase, persists the run state, writes a row to the workflow_approvals table, and waits for a human decision.
You resolve gates three ways: commenting @last-light approve or @last-light reject on the triggering GitHub issue; running /approve / /reject from Slack; or clicking the button on the dashboard. The run resumes exactly where it stopped — no phases re-execute.
Because gates are opt-in per environment, you can ship workflows with gates pre-declared and enable them only in production.
The GitHub App itself has broad permissions (contents read/write, issues read/write, PRs read/write). But every workflow declares a profile — one of read, issues-write, review-write, or repo-write. Before spawning a sandbox, the harness mints an installation token that only has the scopes that profile needs.
The practical effect: a triage run literally cannot push code, a review run cannot open issues, etc. Even if a prompt got compromised, the token handed into the sandbox doesn't have the write permission in the first place.
Edit the YAML in workflows/. Every behavior is a workflow — build.yaml, issue-triage.yaml, pr-review.yaml, cron-health.yaml, etc. A workflow is a list of phases; each phase runs an agent with either an inline prompt (prompt: prompts/architect.md) or a named skill (skill: assure-guardrails).
To change an existing behavior, edit its workflow file or its referenced prompt under workflows/prompts/ or its SKILL.md under skills/. To add a new behavior, drop a new YAML file into workflows/ — the harness picks it up automatically. No TypeScript needed.
Yes. Create a new directory under skills/ with a SKILL.md file — name, description, and tags in the frontmatter, instructions in the body. Skills are plain Markdown that the agent follows as instructions. The agent discovers new skills automatically.
Just install the GitHub App on additional repos — no code changes needed. The bot handles all installed repos automatically. If you want different behavior per repo, you'd need to add conditional logic to the skill files (check repository.full_name in the webhook payload).
The main cost is Claude API usage. Each issue triage or PR review is roughly one agent session. For a repo with a few events per day, expect modest API costs. Build requests (cloning, editing, testing) use more tokens but are less frequent.
Locally, you can use your Claude Code subscription at no extra cost. For production, set an ANTHROPIC_API_KEY and costs depend on usage.
The agent itself is free and open-source.
If the Claude API is unavailable, agent sessions will fail and the error is logged. GitHub webhook events are retried by GitHub automatically if your endpoint doesn't respond, so the work will be picked up when service returns. The execution database tracks all attempts for visibility.
The bot can only do what its GitHub App permissions allow. It can't delete repos, manage org settings, or access repos where it's not installed. Build requests only trigger when a maintainer explicitly @mentions the bot. All actions are logged as session trajectories in logs/.
For extra safety: install the App with read-only Contents permission if you don't want the bot pushing code, and only grant write access to Issues and PRs.