# Sortie

> Sortie turns Jira and GitHub issues into autonomous coding agent sessions. A single Go binary with adapters for Claude Code, Codex, Copilot, and more.

Sortie is an autonomous coding agent orchestrator. Engineers manage work at the ticket level — Sortie handles the rest: isolated workspaces, retry logic, state reconciliation, tracker integration, and cost tracking. Single binary, zero dependencies, SQLite persistence.

For full documentation in a single file suitable for pasting into an AI assistant, see: https://docs.sortie-ai.com/llms-full.txt

Tip for agents: every page linked below is also available as clean Markdown. Request its URL with the HTTP header `Accept: text/markdown` to receive the Markdown rendering instead of HTML (lower token count, no navigation chrome).

## Getting Started

- [Installation](https://docs.sortie-ai.com/getting-started/installation/): Install Sortie on macOS, Linux, or Windows. Supports install script, Homebrew, Go install, Docker, and manual binary downloads.
- [Quick Start](https://docs.sortie-ai.com/getting-started/quick-start/): End-to-end tutorial: poll for issues, spin up workspaces, and run autonomous coding agent sessions locally. No Jira or external APIs required.
- [Connect Sortie to Jira Cloud](https://docs.sortie-ai.com/getting-started/jira-integration/): Tutorial: connect Sortie to a real Jira Cloud project, poll for issues, process them with a mock agent, and see Sortie update Jira status automatically.
- [Connect Sortie to GitHub Issues](https://docs.sortie-ai.com/getting-started/github-integration/): Tutorial: connect Sortie to GitHub Issues, poll labeled issues, run a mock agent, and watch Sortie swap labels to hand each issue off for review.
- [Connect Sortie to Linear](https://docs.sortie-ai.com/getting-started/linear-integration/): Tutorial: connect Sortie to a live Linear team, poll for issues, process them with a mock agent, and watch Sortie update the workflow state automatically.
- [Connect Sortie to Gitea](https://docs.sortie-ai.com/getting-started/gitea-integration/): Tutorial: stand up a local Gitea in a container, connect Sortie to it, poll for issues, process them with a mock agent, and watch Sortie update the label-driven state automatically.
- [Connect Sortie to GitLab](https://docs.sortie-ai.com/getting-started/gitlab-integration/): Tutorial: connect Sortie to a GitLab project on GitLab.com or a self-managed instance, poll for issues, process them with a mock agent, and watch Sortie update the label-driven state automatically.
- [Run the Full Cycle with Claude Code](https://docs.sortie-ai.com/getting-started/jira-claude-end-to-end/): Tutorial: connect Sortie to Jira and Claude Code, clone a repo, let the agent write code, push to a branch, and watch the issue move to In Review.
- [Run the Full Cycle with Copilot CLI](https://docs.sortie-ai.com/getting-started/github-copilot-end-to-end/): Tutorial: connect Sortie to GitHub Issues and Copilot CLI, clone a repo, let the agent write code, push to a branch, and watch the issue move to review.
- [Run the Full Cycle with Codex CLI](https://docs.sortie-ai.com/getting-started/jira-codex-end-to-end/): Tutorial: connect Sortie to Jira and the Codex CLI, clone a repo, let the agent write code, push to a branch, and watch the issue move to In Review.
- [Run the Full Cycle with OpenCode CLI](https://docs.sortie-ai.com/getting-started/jira-opencode-end-to-end/): Tutorial: connect Sortie to Jira and the OpenCode CLI, clone a repo, let the agent write code, push to a branch, and watch the issue move to In Review.
- [Run the Full Cycle with Kiro CLI](https://docs.sortie-ai.com/getting-started/github-kiro-end-to-end/): Tutorial: connect Sortie to GitHub Issues and the Kiro CLI, clone a repo, let the agent write code, push to a branch, open a pull request, and watch the issue transition.
- [Run the Full Cycle with Linear and Codex CLI](https://docs.sortie-ai.com/getting-started/linear-codex-end-to-end/): Tutorial: connect Sortie to Linear and the Codex CLI, clone a repo, let the agent write code, push to a branch, and watch the issue move to Done.
- [Run the Full Cycle with Gitea and OpenCode CLI](https://docs.sortie-ai.com/getting-started/gitea-opencode-end-to-end/): Tutorial: connect Sortie to Gitea and the OpenCode CLI, clone a repo, let the agent write code, push to a branch, and hand the issue off to a review state on a fully self-hosted stack.
- [Run the Full Cycle with GitLab and Claude Code](https://docs.sortie-ai.com/getting-started/gitlab-claude-end-to-end/): Tutorial: connect Sortie to GitLab and the Claude Code CLI, clone a repository, let the agent write code, push a branch, and watch the issue move to a done state.

## Guides

- [How to connect Sortie to Jira](https://docs.sortie-ai.com/guides/connect-to-jira/): Configure Sortie to poll a Jira project: set up API authentication, map workflow states, scope queries with JQL filters, and verify the connection. Covers Jira Cloud and Jira Server / Data Center.
- [How to Connect Sortie to GitHub Issues](https://docs.sortie-ai.com/guides/connect-to-github/): Configure Sortie to poll a GitHub repo: token auth, state labels, issue search filters, handoff configuration, and common error troubleshooting.
- [How to connect Sortie to Linear](https://docs.sortie-ai.com/guides/connect-to-linear/): Configure Sortie to poll a Linear team: set up API-key authentication, map workflow states, scope candidates with an IssueFilter, and verify the connection.
- [How to connect Sortie to Gitea](https://docs.sortie-ai.com/guides/connect-to-gitea/): Configure Sortie to poll a self-hosted Gitea repository: create a scoped access token, set the instance endpoint and owner/repo, map label-driven states, scope candidates, enable pull-request reactions with auto-merge, and verify the connection.
- [How to connect Sortie to GitLab](https://docs.sortie-ai.com/guides/connect-to-gitlab/): Configure Sortie to poll a GitLab project: create a scoped access token, set the endpoint for a self-managed instance, set the namespace path, map label-driven states, scope candidates with query_filter, and verify the connection.
- [How to Use the File Adapter for Local Testing](https://docs.sortie-ai.com/guides/use-file-adapter-for-testing/): Test Sortie workflows without Jira: create a JSON fixture, configure the file adapter, iterate on prompts and hooks, then graduate to production.
- [How to Write a Prompt Template for WORKFLOW.md](https://docs.sortie-ai.com/guides/write-prompt-template/): Write the Go text/template prompt body in WORKFLOW.md: use issue fields, branch on retries and continuations, render blockers, and avoid common mistakes.
- [How to Set Up Workspace Hooks](https://docs.sortie-ai.com/guides/setup-workspace-hooks/): Configure after_create, before_run, after_run, and before_remove hooks to automate git clone, branch management, and cleanup in Sortie workspaces.
- [How to Configure Retry Behavior](https://docs.sortie-ai.com/guides/configure-retry-behavior/): Control how Sortie retries failed agents with session budgets, backoff tuning, stall detection, and timeout settings for production reliability.
- [How to Integrate Security Scanning](https://docs.sortie-ai.com/guides/integrate-security-scanning/): Run gitleaks, semgrep, and govulncheck as Sortie workspace hooks to catch secrets, vulnerabilities, and code issues before agent code reaches a PR.
- [How to Run Multiple Workflows](https://docs.sortie-ai.com/guides/run-multiple-workflows/): Run separate Sortie processes for different projects, teams, or issue types using isolated workflow files, databases, and workspace roots.
- [How to Orchestrate Agents Across Multiple Repositories](https://docs.sortie-ai.com/guides/orchestrate-across-repositories/): Run one Sortie per repo for cross-service features: per-repo git hooks, tracker filters for subtasks, and parent-issue coordination via blockers.
- [How to Configure Dispatch Rules | Sortie](https://docs.sortie-ai.com/guides/configure-dispatch-rules/): Route issues to different agents and prompt templates by label, type, priority, identifier, or assignee using first-match-wins dispatch rules in WORKFLOW.md.
- [How to Resume Agent Sessions Across Restarts](https://docs.sortie-ai.com/guides/resume-sessions-across-restarts/): Understand what Sortie preserves across process restarts, how in-flight sessions recover, and how to verify that no work is lost on shutdown or crash.
- [How to Control Agent Costs](https://docs.sortie-ai.com/guides/control-costs/): Configure per-session budgets, session limits, per-issue token budgets, turn caps, concurrency, and model selection to keep agent API spending predictable.
- [How to Run Sortie as a systemd Service](https://docs.sortie-ai.com/guides/run-as-systemd-service/): Configure Sortie as a persistent systemd service on Linux with a dedicated user, hardened unit file, journald logging, and zero-downtime upgrades.
- [How to Run Sortie as a launchctl Service](https://docs.sortie-ai.com/guides/run-as-launchctl-service/): Configure Sortie as a persistent launchd service on macOS with a property list, environment variables, log files, and automatic restarts.
- [How to Scale Agents with SSH](https://docs.sortie-ai.com/guides/scale-agents-with-ssh/): Distribute autonomous coding agent sessions across remote build machines using SSH. Configure host pools, update hooks, and monitor utilization.
- [How to Set Up PR Reactions | Sortie](https://docs.sortie-ai.com/guides/setup-pr-reactions/): Set up Sortie's PR reaction framework: enable the reactions block, share PR metadata via .sortie/scm.json, configure auto-merge safely, and verify the loop.
- [How to Configure CI Feedback](https://docs.sortie-ai.com/guides/configure-ci-feedback/): Configure CI feedback in Sortie: detect CI failures on agent branches, inject context into prompts, tune retries and log fetching, and set escalation.
- [How to Configure Self-Review | Sortie](https://docs.sortie-ai.com/guides/configure-self-review/): Configure self-review in Sortie: run tests and linters before PR, let the agent review its own diff, tune iteration limits, and verify the loop.
- [How to Configure PR Review Feedback | Sortie](https://docs.sortie-ai.com/guides/configure-review-feedback/): Configure PR review feedback in Sortie: detect Request changes comments, route them to the agent, tune debounce and retries, and set escalation.
- [How to Monitor with Logs](https://docs.sortie-ai.com/guides/monitor-with-logs/): Read, filter, and aggregate Sortie's structured logs in text or JSON format. Grep and jq patterns, lifecycle messages, log verbosity, and log persistence.
- [How to Use PR Label Commands | Sortie](https://docs.sortie-ai.com/guides/use-label-commands/): Request an agent code review with sortie:review or an agent fix with sortie:fix by applying the label to a Sortie-managed pull request, which Sortie consumes on acceptance.
- [How to Monitor with Prometheus](https://docs.sortie-ai.com/guides/monitor-with-prometheus/): Configure Prometheus to scrape Sortie metrics, import the Grafana dashboard, and set up alerting queries for operational monitoring.
- [How to Aggregate Metrics Across Multiple Sortie Instances](https://docs.sortie-ai.com/guides/aggregate-metrics-across-instances/): See dispatch, token, and cost figures across every Sortie process you run using Prometheus federation or the sortie stats export pipe -- no new Sortie feature required.
- [How to Use Sortie in Docker](https://docs.sortie-ai.com/guides/use-sortie-in-docker/): Run Sortie in Docker: build the distroless image, compose Claude Code, Copilot, Codex, or OpenCode agent images with COPY --from, and configure volumes, health checks, and process reaping.
- [How to Deploy Sortie to Kubernetes](https://docs.sortie-ai.com/guides/deploy-sortie-to-kubernetes/): Deploy Sortie to Kubernetes with plain manifests: Deployment, PVC, ConfigMap, Service, Secrets, health probes, storage, and production hardening.
- [How to Use Agent Tools in Prompts](https://docs.sortie-ai.com/guides/use-agent-tools-in-prompts/): Use Sortie's agent tools in prompts: sortie_status for turn budget, cost_budget for token budget, workspace_history for retry context, tracker_api for issues, notify_operator for escalation, .sortie/status for blocks.
- [How to Use Sub-Agents with Sortie](https://docs.sortie-ai.com/guides/use-subagents-with-sortie/): Use coding agent sub-agents in Sortie workflows: clone a repo with agent files, reference them in WORKFLOW.md, and let the agent runtime route tasks.
- [How to Write a Custom Agent Tool](https://docs.sortie-ai.com/guides/write-custom-agent-tool/): Write a custom agent tool for Sortie: implement the AgentTool interface, register it, test it, and expose it over MCP during agent sessions.
- [How to Write a Custom Agent Adapter](https://docs.sortie-ai.com/guides/write-custom-agent-adapter/): Write a custom agent adapter for Sortie: implement the AgentAdapter interface, register it, handle structured or plain-transcript output, classify outcomes, test it, and ship it end to end.
- [How to Troubleshoot Common Failures](https://docs.sortie-ai.com/guides/troubleshoot-common-failures/): Diagnose common Sortie failures: agent won't start, tracker auth errors, template render failures, workspace permission issues, and stuck retries.

## Concepts

- [Architecture](https://docs.sortie-ai.com/concepts/architecture/): Sortie architecture: single Go binary, adapter-based extensibility, SQLite persistence, and spec-first development as an agent orchestrator.
- [Adapter Model](https://docs.sortie-ai.com/concepts/adapter-model/): How Sortie's adapter architecture makes agent and tracker integrations disposable while keeping the orchestration core stable.
- [Persistence](https://docs.sortie-ai.com/concepts/persistence/): Why SQLite persistence is a defining characteristic of Sortie: what survives restarts, warm start vs cold start, and what durable state enables.
- [Orchestration](https://docs.sortie-ai.com/concepts/orchestration/): How Sortie's poll-dispatch-reconcile loop runs agent sessions: candidate selection, retry, state reconciliation, persistence, and self-review.
- [Agent Communication](https://docs.sortie-ai.com/concepts/agent-communication/): Why Sortie splits agent communication into two channels: MCP tool calls for data and .sortie/status files for control signals. Rationale and trade-offs.
- [Agent Tools](https://docs.sortie-ai.com/concepts/agent-tools/): Why Sortie segments agent tools into two tiers: local read-only state versus external dependencies, what each tier guarantees, and how the built-in tools map onto the model.
- [Security Model](https://docs.sortie-ai.com/concepts/security/): Sortie's trust model: workspace isolation invariants, prompt injection surface, secret handling, hook safety, outbound data posture, and bounded failure as a security property.
- [Workspace Isolation](https://docs.sortie-ai.com/concepts/isolation/): How Sortie isolates concurrent agent sessions in per-issue directories: safety invariants, the hook-based model, and why containers were rejected.

## Reference

- [CLI Reference](https://docs.sortie-ai.com/reference/cli/): Complete reference for the sortie CLI: subcommands, flags, short aliases, dry-run mode, run statistics, MCP server, exit codes, signals, and logging format.
- [Workflow Configuration](https://docs.sortie-ai.com/reference/workflow-config/): Reference for every WORKFLOW.md field: tracker, polling, workspace root and retention, hooks, agent, notifications, database, prompt template, server, logging, and SSH worker.
- [Environment Variables](https://docs.sortie-ai.com/reference/environment/): Every environment variable Sortie reads, injects, or filters: SORTIE_* overrides, .env support, agent passthrough, hook env, and install vars.
- [HTTP API](https://docs.sortie-ai.com/reference/http-api/): Complete reference for Sortie's embedded HTTP server: JSON API endpoints, request/response shapes, error codes, and curl examples.
- [Dashboard](https://docs.sortie-ai.com/reference/dashboard/): Sortie embedded HTML dashboard reference: summary cards, sessions table, retry queue, run history, detail panels, cost estimation, and auto-refresh.
- [Prometheus Metrics](https://docs.sortie-ai.com/reference/prometheus-metrics/): Complete reference for all Prometheus metrics exposed by Sortie: gauges, counters, histograms, labels, PromQL examples, and Grafana dashboard.
- [State Machine](https://docs.sortie-ai.com/reference/state-machine/): Reference for Sortie's internal orchestration states, run attempt phases, transition triggers, retry backoff, and reconciliation behavior.
- [Reactions](https://docs.sortie-ai.com/reference/reactions/): Reference for Sortie's reaction framework: the shared poll, fingerprint, deduplicate, dispatch, and escalate lifecycle, plus the ci_failure, review_comments, bot_review, merge_conflicts, auto_merge, and merge_completion kinds with every field, default, and safety rule, including post-merge issue closure to a terminal state.
- [Label commands](https://docs.sortie-ai.com/reference/label-commands/): Reference for Sortie's PR label commands: the one-shot sortie:review and sortie:fix labels an operator applies to a Sortie-managed pull request to dispatch a read-only review session or a read-write fix session.
- [Errors](https://docs.sortie-ai.com/reference/errors/): Reference for all Sortie error kinds: tracker errors, agent errors, workspace failures, worker exit types, retry behavior, and operator actions.
- [Agent Extensions](https://docs.sortie-ai.com/reference/agent-extensions/): Reference for Sortie agent extensions: .sortie/status file protocol, tracker_api, sortie_status, workspace_history, cost_budget, and notify_operator tools with schemas and errors.
- [Claude Code Adapter](https://docs.sortie-ai.com/reference/adapter-claude-code/): Claude Code agent adapter reference: configuration, session lifecycle, JSONL event stream, token accounting, errors, SSH remote execution, and auth.
- [Copilot CLI Adapter](https://docs.sortie-ai.com/reference/adapter-copilot/): Copilot CLI agent adapter reference: configuration, session lifecycle, JSONL event stream, token accounting, errors, SSH remote execution, and auth.
- [Codex CLI Adapter](https://docs.sortie-ai.com/reference/adapter-codex/): Codex CLI agent adapter reference: configuration, session lifecycle, JSON-RPC protocol, token accounting, errors, SSH remote execution, and auth.
- [Jira Adapter](https://docs.sortie-ai.com/reference/adapter-jira/): Jira tracker adapter reference: configuration, authentication, API operations, field mapping, ADF flattening, pagination, rate limits, and error mapping. Covers both Jira Cloud (REST API v3) and Jira Server / Data Center (REST API v2).
- [OpenCode CLI Adapter](https://docs.sortie-ai.com/reference/adapter-opencode/): Complete reference for the OpenCode CLI agent adapter: configuration, session lifecycle, CLI argument mapping, event stream, token accounting via export subprocess, error handling, SSH remote execution, and multi-provider authentication.
- [GitHub Adapter](https://docs.sortie-ai.com/reference/adapter-github/): GitHub Issues tracker adapter reference: configuration, auth, API operations, field mapping, label-based state, pagination, rate limits, and errors.
- [Linear Adapter](https://docs.sortie-ai.com/reference/adapter-linear/): Linear tracker adapter reference: GraphQL configuration, API-key authentication, workflow-state mapping, identifiers and team scoping, query_filter, pagination, rate limits, and body-first error mapping.
- [Kiro CLI Adapter](https://docs.sortie-ai.com/reference/adapter-kiro/): Complete reference for the Kiro CLI agent adapter: configuration, session lifecycle, plain-transcript headless output, credential preflight, time-based budgeting, error handling, cwd-scoped resume, and SSH remote execution.
- [Gitea Adapter](https://docs.sortie-ai.com/reference/adapter-gitea/): Gitea tracker and SCM adapter reference: self-hosted REST v1 configuration, token authentication, label-driven state, owner/repo scoping, query_filter, Link pagination, error mapping, pull request reviews, review decision, mergeability, auto-merge, branch cleanup, CI status, the write:repository scope, and Forgejo compatibility.
- [GitLab Adapter](https://docs.sortie-ai.com/reference/adapter-gitlab/): GitLab tracker adapter reference: REST v4 configuration, PRIVATE-TOKEN authentication, label-driven state, namespace-path or numeric project scoping, the query_filter allowlist, Link pagination, error mapping, and Community Edition compatibility.
## Optional

- [Changelog](https://docs.sortie-ai.com/changelog/): Release history for Sortie. All notable changes, new features, bug fixes, and breaking changes by version.