Turn

Turn is an open-source coding agent for the terminal.

Give it a task and work alongside it as it explores your repository, changes code, runs checks, and explains what changed. Keep guiding it in the same session, or hand work off and come back when a pull request is ready for review.

What you can do

• Work with your repository — ask for a fix, a feature, an explanation, or a review.
• Stay efficient — Turn prefers the smallest change that works: reuse what is already here, skip speculative abstraction, and keep diffs short.
• Stay in the loop — see the plan and work as it happens, steer the agent without waiting, or stop it at any time.
• Pick up where you left off — sessions are saved per project.
• Hand off work — enqueue durable jobs on the handoffs board; a worker runs each one in isolation and opens a pull request.
• Start from an issue — name a GitHub or Linear issue and Turn reads it before it plans.
• Use your preferred provider — sign in with OAuth or an API key.

Get started

Install from npm — a compiled binary for your platform, no runtime required:

npm i -g @anturno/turn
turn login
turn

Or download a release archive for your OS from GitHub Releases, extract it, and run turn from that folder (keep the extracted files together — skills and assets sit next to the binary):

tar -xzf turn-darwin-arm64.tar.gz
cd turn-darwin-arm64
./turn login
./turn

Or put the folder on your PATH.

From source (requires Bun 1.2+):

bun install
bun run start login
bun run start

Then open a repository and ask Turn to do something:

turn "find and fix the failing tests"

Log in from the terminal or the app:

turn login anthropic --oauth
turn login anthropic --api-key
turn auth status

Everyday use

Start Turn in the repository you want to work on:

turn

Useful options:

turn --continue
turn --resume ./path/to/session.jsonl
turn --cwd ./other-project
turn --model anthropic/claude-sonnet-4-5

Inside the app:

| Key or command | What it does | | --- | --- | | Enter | Send a request, or steer a running turn | | Esc | Stop the current turn | | Tab | Switch between your session and the handoffs board | | / | Open the command menu | | /new | Start a fresh session | | /resume | Reopen a saved session | | /model | Choose a model | | /handoff | Enqueue work for a background agent |

Start from a GitHub issue

Turn reads GitHub through the GitHub CLI, so it uses the account you already have — including private repositories and GitHub Enterprise hosts:

gh auth login

Then name the issue instead of describing it:

turn "#123"
turn "anturno/turn#123"
turn "https://github.com/anturno/turn/issues/123"
turn "#123, but leave the docs alone"

Turn reaches for the issue on its own when your request names one. To ask for it outright, type /skill:github-issue in the app and add the reference.

A bare #123 resolves against the repository you opened Turn in. Turn fetches the title, body, comments, labels, state, assignees, and milestone before it plans or edits, and keeps the Markdown intact. If the number turns out to be a pull request — GitHub numbers both from one pool — Turn says so rather than inventing issue context.

Intake is read-only: Turn never comments on, edits, labels, or closes the issue. Issue text is treated as untrusted task data, so a comment cannot talk Turn into ignoring your request or the repository's own rules.

Start from a Linear issue

Give Turn a Linear personal API key (Linear → Settings → Security & access → Personal API keys):

export LINEAR_API_KEY=lin_api_...

Then name the issue instead of describing it:

turn "TURN-1"
turn "TURN-1, but keep the CLI flags out of it"

Turn reads the issue — description, comments, parent and child issues, labels, state, priority, estimate, team, project, milestone, people, attachments, and Linear's suggested branch name — before it plans or changes anything. It only reads: it never comments on, updates, or transitions the issue, and it works the same in read mode.

Hand off work

Use /handoff (or free-text on the handoffs board) when you want Turn to continue without keeping the session open. Jobs land on a durable queue; the board drains them in-process when free, or you can run a headless worker:

turn handoff work

Use --once to drain available work and return to the shell. Inspect the queue with handoff list and handoff show <id>.

Orphan data under .turn/missions/ from older Mission-based runs may remain on disk; Turn no longer reads or migrates it.

Develop Turn

bun run check
bun run typecheck
bun test

See Contributing for development and pull request guidance.

Learn more

• Architecture
• Domain glossary
• Security
• Changelog

License

Apache-2.0