Noctra

AGENTS.md at the repo root is a symlink to this file, so the Codex backend (AGENT_BACKEND=codex) reads the same project guidance Claude does. Edit CLAUDE.md; AGENTS.md follows.

Autonomous Linear-to-PR agent in Go. Polls Linear (or GitHub Issues / Jira) for tickets in a trigger state or with a trigger label, dispatches a coding agent to implement them, creates PRs, and moves tickets to review. Up to three work loops share one WaitGroup, worker pool (MAX_CONCURRENT) and active-set, plus a credential check that only alerts:

ticket loop  → source.Fetch → pipeline.process (bounded goroutine)
  → repo.Resolve → repo.CreateOrResumeWorktree → agent.Run → check output
  → (optional) review.Gate → commit/push → gh pr create → source.MarkReady
PR loop      (AUTO_ITERATE_PRS) → watch.Scan → pipeline.iteratePR → push to the same branch
sweep loop   (SWEEP_ENABLED)    → scheduler.Plan → pipeline.processSweepTask → maintenance PR
auth loop    (AUTH_CHECK_SCHEDULE, daily at noon by default) → authcheck.RunAll (logins + cloned repos reachable) → authcheck.Tracker → notify while broken / on recovery

• TRIGGER_MODE=state (default) polls the TRIGGER_STATE column. TRIGGER_MODE=label polls for TRIGGER_LABEL regardless of column and removes the label after dispatch so the ticket isn't re-polled; the trigger-state ID is then not resolved, but the in-review state still is.
• Worktrees live at ~/.noctra-worktrees/<IDENTIFIER> so tickets run concurrently.

Guardrails

Each of these has caused a real incident; a plausible-looking patch breaks them easily.

• ⚠️ The noctra/ branch prefix is reserved for branches Noctra creates — applies to humans and any agent working here. For hand-written work use fix/, feat/, docs/, chore/ or eng-<n>-<slug>. In personal-token mode a running instance claims any noctra/* PR authored by its own GitHub account (ListNoctraPRs filters --author @me plus the prefix), iterates on its review feedback and pushes commits that collide with yours (PR #143). App mode filters by --author app/<slug>, but the rule holds for anyone in token mode.
• Zero comments in Go source — see Code style.
• log_offset: agent logs (logs/<IDENTIFIER>.log under the config dir) append across attempts, each headed --- Attempt <timestamp> ---. agent.OffsetBefore records the size before a run and agent.ReadAfter reads only the new tail; BlockedLine and HasRateLimit scan that tail. Scanning the whole file re-detects failures from earlier attempts.
• Every gh call goes through github.Command / CommandInDir, never a raw exec.CommandContext(ctx, "gh", …), or app mode silently falls back to personal credentials (github-identity).
• Fresh ticket dispatch uses repo.CreateOrResumeWorktree, not CreateWorktree. A run that pushed but died before gh pr create leaves an orphaned remote branch; re-branching from origin/<main> builds a non-descendant that origin rejects, so the ticket burns a full run per retry until MAX_RETRIES.
• Any git call that mutates a shared clone runs inside repo.lockRepo. Two tasks on one clone otherwise race on .git/config and one is silently dropped.
• Names and hidden markers are read back by the PR watcher and lessons extractor. Change branch names, identifiers, commit/PR wording, footers or markers only through the naming skill.
• Manual sweeps go through Pipeline.TriggerSweep into the existing sweep loop; a second dispatcher would bypass the worker-pool cap (sweeps).
• After changing internal/dashboard/web/, run yarn build and commit static/, and keep the bundle a single inlined file (dashboard).
• Report an agent failure through pipeline.describeAgentFailure, not runErr.Error(). The exec error is just exit status 1; the CLI's own reason (and an expired login, via agent.AuthFailureLine + agent.LoginHint) is in the log tail.
• Start agent runs with p.runAgent, never backend.Run directly. It appends the ENGLISH_VARIANT spelling rule (agent.LanguageSection) to every prompt; a direct call writes in whatever spelling the model defaults to.
• Keep new operationally significant config visible in the startup banner (pipeline.banner).

Multi-repo routing

The target repo is chosen per ticket; there is no repo registry.

1. Linear project directive — a Repo: <owner/name | git URL> line (optionally Branch: <name>) in the project's content, falling back to description (linear.Project.RepoDirective). repo.ResolveDirect clones it on demand into ~/.noctra-repos/<slug> (lock-guarded via mkdir(2)). owner/name expands to GitHub HTTPS; full https:///git@ URLs are used verbatim. With no Branch:, the default branch comes from origin/HEAD (fallback MAIN_BRANCH).
2. REPO_PATH — single-repo fallback (repo.Resolve); otherwise the ticket is skipped with a Linear comment.

Auto-iterate resolves the same way from the PR URL (prRepoOwnerRepo → ResolveDirect). The set of known repos is whatever has been cloned: repo.Resolver.AllRepoPaths scans ReposBase (plus REPO_PATH), and AllRepoRemotes feeds the PR watcher, re-read on every scan.

Config directory

Config defaults to ~/.noctra/ (.env, logs/, state.db). If the current directory contains .env, .env.example or go.mod, Noctra uses cwd instead, so go run works without touching ~/.noctra/ (resolveScriptDir() in cmd/noctra/main.go; config.DefaultConfigDir()). Every variable is documented in .env.example.

Code style

⚠️ Zero comments

This codebase contains no comments. Do not add any. This applies to humans and every agent, and covers doc comments on exported symbols, package docs, TODO/FIXME, section banners and end-of-line asides. The urge to explain is a signal to rename a symbol or extract a function.

The only permitted // lines are directives: //go:embed, //go:build, //go:generate, //nolint:…, // Code generated … DO NOT EDIT. Enforced in CI by make check-comments (scripts/check-comments.sh).

The why lives in this file for cross-cutting behaviour, in the subsystem skills below, and in architecture Invariant 7 for file-level facts (lock ordering, cursor semantics, flag quirks, encoding traps). When a change's reasoning isn't evident from the diff, add a row there — not in the source.

Skills

Read .claude/skills/<name>/SKILL.md before working in its area. Codex and Copilot don't auto-discover skills but can open these paths.

Build and test

Run all of these before every push; CI fails on any of them.

go build -o noctra ./cmd/noctra
go test -race ./...
go vet ./...          # must be clean
golangci-lint run ./...   # CI pins v2.5.0 (.github/workflows/ci.yml); catches errcheck, which vet doesn't
make check-comments