Set up CircleIt.

2. Connect Claude Code

Install the plugin once, in Claude Code. It installs for every project and every new session, in the terminal and in the Claude desktop app:

• › /plugin marketplace add circleit-ai/circleit-plugin
• › /plugin install circleit@circleit

From a shell, the same is claude plugin marketplace add circleit-ai/circleit-plugin and then claude plugin install circleit@circleit.

Connect this computer

Run this, or ask Claude to “connect CircleIt”. Your browser opens; approve the connection, and every session on this computer is connected. You do this once per computer, on up to 2 computers.

• › /circleit:connect

Allow CircleIt’s tools

Claude Code asks before each CircleIt tool call, so feedback that arrives while you’re away waits at the prompt. Allow them once, in ~/.claude/settings.json:

{
    "permissions": {
        "allow": [
            "mcp__plugin_circleit_circleit"
        ]
    }
}

Already have a permissions.allow list? Add this rule to it: mcp__plugin_circleit_circleit

Or choose “Yes, and don’t ask again” the first time Claude Code asks; that covers one tool in one project. This covers CircleIt’s own tools only. File edits and commands still follow your Claude Code permission mode.

Sessions that were already open

In the terminal, run /reload-plugins. If Claude Code says the reload changes MCP tools, run /reload-plugins --force. That starts CircleIt in the session, so feedback wakes it as it would a new one. In the Claude desktop app, open sessions pick CircleIt up by themselves within a few seconds of installing.

• › /reload-plugins

How feedback arrives

In a terminal session, the plugin’s monitor wakes the session when feedback arrives, even when it is idle. In the desktop app, feedback reaches Claude with your next message, or when it finishes what it is doing. To have Claude wait for feedback and handle each one as it comes, run /circleit:watch.

3. Connect Codex

Install the plugin from a shell:

• $ codex plugin marketplace add circleit-ai/circleit-plugin
• $ codex plugin add circleit@circleit

Then open Codex, run /hooks and approve CircleIt’s SessionStart hook. You only do this once. The hook tells CircleIt which thread and folder Codex is working in, so feedback can wake that thread.

• › /hooks

To connect this computer, ask Codex to connect CircleIt. Your browser opens; approve the connection. Codex runs the plugin’s tools without asking, because they are marked non-destructive, so there is nothing to allow.

• › connect CircleIt

Feedback is queued to your Codex thread, and an idle thread picks it up within about 10 seconds. Codex loads plugins when a session starts, so start a new session in the project’s folder after installing.

4. Invite people

The owner and approvers invite people from Team › People › Invite people, as a Sender or an Approver. On Personal, which is just you, you can’t invite anyone.

1. They get an email with an Accept invitation button. The invitation lasts 3 days.
2. They create an account with their email, or continue with Google, and join your team.
3. The welcome page walks them through adding the extension, connecting it and sending their first feedback.

People who only send feedback are free and see plain statuses: Waiting for your developer, Picked up, Being worked on, Done, Question for you. Anyone who connects Claude Code or Codex becomes a developer, and developers are what the plan pays for.

5. Approval

Approval is off until you turn it on. Set a person or a site to Needs approval. Their feedback waits until the owner or an approver approves it. Approvers can edit a comment, take a mark out, or reject it with a note.

• For a person: in Team › People, use the Automatic or Needs approval switch beside each sender.
• For a site: on the Projects page, or under Approval for sites in Team.

Approvers get an email when something is waiting, and the inbox shows a To approve count. Open an item to review it: edit comments, change the new wording of a text change, take marks out, then press Approve, or Reject with a note for the sender. Feedback from the owner and approvers always goes straight through.

6. Projects and Goes to

There is one project for each code repository where an agent runs with CircleIt, plus one for each new site someone sends from. The owner or an approver can add one too, on the Projects page.

Addresses

Each project has the addresses its site runs on. The plugin adds the local ones when a session starts: the APP_URL in .env, Herd or Valet .test domains, and dev-server ports. Add your staging and live addresses with Edit on the Projects page, so feedback from them goes to the right project.

Who can see it

A project is open to everyone in the team, or only to the people you tick. The owner and approvers always see every project. Someone who can’t see a project can’t see its feedback or send to it.

Goes to

Each project’s feedback goes to one developer’s Claude Code or Codex. A project goes to the first developer whose Claude Code or Codex opens it. The owner, approvers and developers can change it with Goes to on the Projects page, or set it to Anyone with it open. A developer who sends feedback on a project they have open gets it in their own session, and another developer can take an item over with Send to my Claude.

7. Troubleshooting

The extension says it isn’t connected

Open the extension and use its connect button. It opens a CircleIt page: sign in if asked, and press Connect this browser. If that page says the extension didn’t answer, check that the extension is installed and turned on in this browser profile, reload the page and try again.

The agent says it isn’t connected

Run /circleit:connect in Claude Code, or ask Codex to connect CircleIt, and approve the connection in your browser. Ask the agent to run circleit_status to see the connection, the project and how feedback reaches it.

Feedback went to the wrong project

The extension picks the project whose addresses match the page. Add the page’s address to the right project with Edit on the Projects page. Before changing any code, the agent checks the address too, and asks instead of guessing when the page belongs to another project.

“To work on this site, ask an approver to set it up.”

The site belongs to a project you can’t see. Ask the owner or an approver to add you to that project under Who can see it on the Projects page.

“You’re already connected on 2 computers”

A developer can connect up to 2 computers. Disconnect one on the approval page that shows this message, or revoke it on the Setup page, then connect again. Connecting the same computer again replaces its old connection.

Feedback only arrives when I type a message

The session has no monitor running: the Claude desktop app, or a terminal session whose monitor didn’t start. Restart the terminal session for automatic wake-ups, or run /circleit:watch to have Claude wait for feedback.

Claude Code stops at a permission prompt

Allow CircleIt’s tools once, as in section 2. File edits and commands the agent runs still follow your own permission mode.

A Codex thread doesn’t wake up

Check that CircleIt’s SessionStart hook is approved in /hooks. Until it is, CircleIt can’t wake the thread, and feedback waits in the inbox.

Still stuck? Email [email protected].