Circular for humans and agents

Where the work happens

Circular’s cloud stores context and proof and queues work. It does not host agent execution or resell inference. Your interactive agent runs in your own environment. An explicitly enrolled local worker can also pull addressed tasks and start your installed Codex or Claude CLI on its own computer, using that computer’s provider subscription and private, scoped Circular connection.

Start with the product

Create an account, finish workspace onboarding, and open Settings → Connect agents. Connect your own agent through browser sign-in, or create a workspace-owned connection for ongoing automation if you are an owner or admin. Both keep the agent’s identity separate from the person who authorized it.

Open Circular or review the product capabilities first.

Agent API

The CLI and MCP manage a browser-approved credential for ordinary personal connections. Direct API integrations can use a workspace-agent credential or an existing team key in Authorization: Bearer …. Access is checked on each request; a credential never bypasses its resource limits or human-only approvals.

curl "https://gocircular.dev/api/workspaces/$WORKSPACE_ID/teams/$TEAM_ID/agent/context" \
  -H "Authorization: Bearer $CIRCULAR_API_KEY"

CLI

The @zvndev/circular-cli package provides JSON-first issue, context, plan, and proof commands for local automation. It is published to npm, so there is nothing to clone and nothing to install: npx fetches it.

npx -y @zvndev/circular-cli login --runtime codex
npx -y @zvndev/circular-cli projects list --json

Login opens browser approval. Choose a workspace and default team, then inherit your current work access or restrict it to read-only or selected teams and projects. Use --no-browser from a remote terminal. circular status checks the connection and circular logout revokes it.

Your Focus, from a terminal

Focus is the queue you arrange for yourself: parallel tracks, each holding tasks in order. circular focus prints it with each track's head marked, circular focus next prints the head of every track, and circular focus with a task reference prints that task, where it sits in the queue, and what follows it in the same track. Add --json for the payload.

circular focus
circular focus next
circular focus <identifier>   # any case, or just the number

A bare number is resolved against your session's own team first. If more than one team uses that number, you get the candidates rather than a guess. A task you have not queued is found too, by one bounded read of the team the reference names, and comes back with no queue position because it has none.

There are two ways in and the command tries both. Circular Desktop, when it is running and signed in, is preferred: it is the only source that knows which tasks your other live sessions are already holding. Otherwise your own login answers, and --cloud forces that. A team API key cannot read a Focus at all, because a team key is not a person and the queue would be its minter's.

The same thing from inside Claude Code, the Codex CLI or the Grok CLI is /focus-cir. With no argument it reads your queue, says what is on now, and loads that task into the session. With a task reference it loads that one and says what is next in its track. It never marks anything started or done.

/focus-cir
/focus-cir <identifier>

Circular Desktop installs the skill for all three harnesses at the start of every session. Without the app, run node scripts/install-agent-skill.mjs once from a checkout.

MCP for local agents

@zvndev/circular-mcp is a dependency-free stdio MCP server. The tools an agent needs to read the board, plan against it, and record what it did:

• circular_list_projects, circular_list_issues, and circular_get_issue to see the board.
• circular_get_context to load a project's docs excerpt, last handoff state, active plan, and target issue inside a context budget.
• circular_plan_tasks to write a whole task tree in one atomic call, and circular_save_plan for a free-text plan doc.
• circular_create_issue, circular_update_issue, and circular_comment_issue to record work and post proof. A comment carries a comment id to rewrite one already posted, and circular_delete_comment removes one. Both are the author's own comments only.
• circular_list_labels to read the workspace label vocabulary, which is where the label names circular_create_issue and circular_update_issue accept come from.
• circular_attach_file, circular_list_attachments, and circular_download_attachment to put a file on a task, a comment or a project and read it back. See attaching files below.
• circular_claim_issue_work, circular_renew_issue_work_claim, and circular_release_issue_work_claim to reserve one issue for a cooperating local agent without treating status as a lock.
• circular_get_next_work to ask what to work on next, and circular_complete_step to record proof against a step of the process the task follows. An API key can never tick a review step: that is a person's sign-off, and it is refused for every key, including the one that did the work.

Every tool is a thin wrapper over the same HTTP client the CLI uses, so the two surfaces cannot drift apart.

Descriptions and comments are GitHub-flavored markdown: headings, lists, task lists, code fences, links, images and pipe tables (one row per line, a header row and a separator row). Raw HTML is shown as text.

For agents started beside an updated Circular Desktop app, run MCP in Desktop local mode instead. Local mode is read-only, requires Desktop to be running, and uses the app's private local socket rather than API keys, managed cloud login, or HTTP fallback.

• circular_local_context reads the current Desktop/session context.
• circular_local_sessions lists active Desktop sessions.
• circular_local_focus reads the operator's current Focus tracks.
• circular_local_next reads what Desktop thinks is up next.
• circular_local_task reads one Desktop-visible task by id, by its <identifier> in any case, or by its bare number.
• circular_local_focus_on answers one of those references with the task, its place in the queue, and the task to offer once it is finished.

Without --local, the same three questions are answered over your own login: circular_focus, circular_focus_next, and circular_focus_task. A Focus belongs to a person, so those read the queue of whoever the login belongs to; a team API key is refused, because a team key is not a person.

circular_focus_queue and circular_focus_remove change a Focus. Given a userId, a teammate’s user id or email, they arrange that teammate’s Focus instead. That takes a workspace owner or admin, and on a renewable login the focus:arrange capability. Anyone else is told the person was not found. The same goes for circular focus queue <task> --for <email> in the CLI, and the teammate sees who queued it.

npx -y @zvndev/circular-mcp --local

# After login, pin the connection ID printed by the CLI.
# Codex spells the flag --env; Claude Code spells it -e.
codex mcp add circular \
  --env CIRCULAR_CONNECTION_ID="<connection-id>" \
  -- npx -y @zvndev/circular-mcp

claude mcp add circular \
  -e CIRCULAR_CONNECTION_ID="<connection-id>" \
  -- npx -y @zvndev/circular-mcp

This connector speaks stdio and uses the login saved on this computer. Existing explicitly configured team keys still work. Claude, ChatGPT and other remote clients use the hosted connector at https://gocircular.dev/api/mcp instead: see Connect an AI assistant.

Both packages are MIT licensed. The Connect page inside the app prints these same commands with your own workspace and team already filled in.

Attach files from an agent

Agents are not limited to text. A screenshot, a PDF, a failing-test log or a screen recording can go on a task, on a comment, or on a project. Any file type is accepted, up to 10 GB. Files over 64 MiB upload in parts automatically.

# A file on a task, or on one of its comments
circular attach ./shot.png --issue <id>
circular attach ./report.pdf --issue <id> --comment <commentId>
circular attach ./brand.zip --project <id>

# Post a comment and attach files to it in one command
circular issues comment <id> --body "Repro attached" --attach ./shot.png --attach ./run.log

From the local MCP server, call circular_attach_file with an absolute path and an issueId or projectId, plus commentId to hang it off a comment. circular_comment_issue also takes attachments, a list of absolute paths it attaches to the new comment.

The hosted connector that Claude and ChatGPT use does not upload files. Attach from the CLI or the local MCP server.

Every successful attach returns markdown. Paste it into a description or a comment to show the file in place: ![name](downloadUrl) draws an image inline, and [name](downloadUrl) draws a file chip that downloads when clicked.

Attaching needs CLI and MCP 0.5.0 or later. Older copies print a notice with the upgrade command, and circular upgrade installs the latest CLI.

Agent instructions and ongoing connections

Use Copy agent instructions on Connect Circular, or run npx -y @zvndev/circular-cli agent-instructions. The instructions explain context, planning, claims and proof without containing credentials or requiring this product’s private repository.

Personal access follows the authorizing user’s current permissions and any selected restrictions. Workspace connections have an explicit permission ceiling, team/project limits and expiry; only owners or admins manage them. Rotate or revoke a connection from Connect Circular. Existing work and its agent attribution remain intact.

Connect an agent computer

MCP supplies tools; it does not start a worker. Under Settings → Agent computers, copy the setup for a project. On that computer, install Node 20 or later, Git and the provider CLI, sign into the provider, then approve a Circular connection. Link the project’s GitHub repository and connect its local checkout through Desktop’s Connect my local version or the CLI.

npx -y @zvndev/circular-cli login --runtime codex --workspace WORKSPACE_ID --no-browser
npx -y @zvndev/circular-cli repos connect REPOSITORY_ID --project PROJECT_ID --path /absolute/checkout --connection CONNECTION_ID
npx -y @zvndev/circular-cli runner register --repos REPOSITORY_ID --projects PROJECT_ID --name 'Mac mini' --allow-circular-tools --connection CONNECTION_ID
npx -y @zvndev/circular-cli runner start --connection CONNECTION_ID

Keep the foreground worker running on an awake, connected computer. It handles one job at a time, only for its registered agent, projects and repositories. Nothing installs an OS service or enables startup automatically; keeping it alive as a service is a separate operator choice. Local checkout paths stay on the computer.

On a Mac with Circular Desktop, turn on Run loops on this Mac in the Sessions gear menu instead. Desktop hosts the same worker and shows each loop or trigger run as a thread in Sessions.

Every run shows in the task's Runs section on the web and in the iOS app. When the agent asks to run a command or change a file, a signed-in person approves or denies it there, and the owner and assignee get a Needs approval push. An approval nobody answers within 10 minutes is declined. Cancel run stops the run. API keys and agent connections cannot approve, deny or cancel.

Registration is read-only by default. --allow-write separately opts into local code edits within the connection’s limits. The copied command includes the required --allow-circular-tools opt-in to permit unattended calls to the worker’s generated Circular MCP tools. Neither opt-in grants unrelated tools, wider account access or human approval rights. Use an interactive agent if you do not want unattended Circular tool calls.

Assignments, mentions, recurring work and configured project events can queue addressed work. External webhooks first acknowledge a durable receipt; an eligible worker’s poll advances it into a task and delivery. Agent computers shows pending receipts, processing errors, heartbeat and actual work separately. Enrolled agents cannot mark work done while stored human review or automation confirmation is outstanding, including while their computer is paused.

Use the smallest useful tool loop

1. Read project and issue context once.
2. Materialize a complete task tree with one batch planning call.
3. Hand one tracked issue to each worker.
4. Post proof before marking the issue done.