GitHub
Connect your repository so specs include real file paths from your codebase.
Setup
- Go to Settings → Integrations → GitHub
- Click Connect
- Authorize Circuit and select a repository
What Circuit Reads
Circuit uses repository-level read access to understand your codebase. 9 signals, all read-only:
Specs are constrained to what actually exists in your repo. File paths in the spec come from GitHub signals only — the system won’t generate paths it hasn’t seen. The most important signal is file signatures: without them, the Codebase Context section is omitted entirely and file paths fall back to inference.
| Signal | Effect on spec |
|---|---|
| File signatures | Exports, types, key functions and import graph from relevant source files. Gates both Files to Touch and Codebase Context — without this signal, Codebase Context is omitted entirely and file paths are inferred, not grounded. |
| .cursorrules / CLAUDE.md / CONTRIBUTING.md | Reads your team’s AI coding conventions — specs name the right things (“add a useExportStream hook” rather than a generic description) and follow your rules, not generic best practice. |
| Testing patterns | Sample test file from your repo — “Done when” criteria reference your actual test framework and style. Executable, not aspirational. |
| Directory structure | Compact file tree — validates that suggested paths exist in the actual project layout. |
| Open issues | Semantically similar open issues — if any match, the spec gets a Heads Up section warning the developer about existing work to avoid duplicating. Omitted if no matches. |
| File relevance signals | Recently changed files boost discovery scoring — actively touched files surface as candidates first in Files to Touch. |
| Tech stack | Detected framework and language — prevents framework mismatch in suggestions. Appears as the repo header in the spec. |
| CI/CD + config files | Workflow names and config files present — “Done when” criteria can reference real commands (npm run test:coverage, pytest backend/tests/) rather than generic descriptions. |
| README | Project overview and setup context — fallback when no AI config files exist. |
Circuit never writes to your repository.
Grounded, not guessed
Without a GitHub connection, the spec prompt falls back to inferring file paths from common project conventions. The Codebase Context section is omitted entirely. Files to Touch contains plausible guesses, not verified paths.
With GitHub connected, file signatures are present. The prompt rule is explicit: specs may only reference files from the GitHub context — no invented paths. The Codebase Context section appears, covering architecture patterns, how to test, and how this team writes code. Files to Touch contains real paths from the actual codebase.
Connecting GitHub also means Circuit reads your .cursorrules and CLAUDE.md before each spec is generated — the same source of truth as Cursor and Claude Code. And if semantically similar open issues exist, the spec gets a Heads Up section warning the developer about existing work, so the spec doesn’t duplicate something already tracked.
See Working with Specs for the full spec structure.
Disconnect
Go to Settings → Integrations and click Disconnect next to GitHub. Existing specs keep their file paths. New specs generated after disconnecting will omit the Files to Touch section.