Guides

Use CoDev from Claude Code or Codex

Connect your own agent to your CoDev workspaces and Rooms, and coordinate with teammates' agents.

Keep working in the agent you already use. CoDev's connector lets Claude Code, Codex, ChatGPT and Claude read and work in your CoDev workspaces and Rooms, as you. The CoDev web app stays the source of truth: every change your agent makes through the connector shows up there, in the workspace history and to your teammates.

Connect

To connect Claude Code, Codex and Cursor in one go, copy the setup prompt from CoDev's home page and paste it into your agent (see the Quickstart). Your agent installs the CoDev CLI, signs you in (or creates your account), asks you which of them to connect, and adds everything below to the ones you choose, with Claude Code and Codex already signed in (both get a plugin named codev, listed in Claude Code’s /plugin and Codex’s /plugins; in Codex, also open /hooks and review and trust CoDev’s hooks before mirroring, conflict warnings and the session briefing can run): each gets a short-lived sign-in from the CLI whenever it connects (codev mcp-headers), so neither opens a sign-in page of its own. Settings → Security lists them under the computer that connected them, with whether their chats show in CoDev; Disconnect signs one out, and codev disconnect on that computer also removes its plugin. Run codev login and codev setup to connect one again. Setup also installs CoDev's extension in VS Code and Cursor, which signs their agents in from the editor: see Use CoDev from VS Code or Cursor. To do it by hand instead:

The connector's address is https://www.trycodev.com/api/mcp.

Claude Code

claude mcp add --transport http codev https://www.trycodev.com/api/mcp

Then run /mcp in Claude Code and choose codev to sign in.

Codex

codex mcp add codev --url https://www.trycodev.com/api/mcp

codex mcp login codev

The second command opens your browser to sign in.

ChatGPT and Claude

Add https://www.trycodev.com/api/mcp as a custom connector in the app's settings. For Claude, Add to Claude on CoDev's home page opens Claude's Add custom connector dialog with CoDev already filled in: choose Continue. This connector is for Claude chats and Rooms. Claude's desktop app also hands it to its Code tab, so if you use Claude Code there, codev setup already gives it CoDev, and adding both shows CoDev's tools twice.

Each connection opens CoDev's Connect an app page in your browser. It lists what the app is asking for:

Permission	Lets the app
Rooms	See your Rooms, post in them as you, and start CoDev AI replies.
Workspaces	See your workspaces, their agent chats, files and changes, and ask their agents to work as you.
Workspace edits	Edit files, run commands, use Git and start your workspaces as you, and join workspaces from invites you give it.

Choose Allow to connect. Everything the app does is checked against your role, exactly as in the web app: a viewer can read but can't edit files, commit or run agents. To disconnect an app, open Settings → Security → Connected apps. Changing your password disconnects every app.

What your agent can do

Tool	What it does
`codev_list_workspaces`	Lists your workspaces, whether each is running, and a link to open it.
`codev_join_workspace`	Joins a workspace from an invite link you give your agent: a share link or an emailed invitation. It also says where to work: on your computer through `codev clone`, or in the workspace.
`codev_list_workspace_chats`	Lists a workspace's agent chats.
`codev_read_workspace_chat`	Reads an agent chat and says whether its agent is still working.
`codev_ask_workspace_agent`	Asks the workspace's own agent to work. Agents `codev setup` signed in use it only when you ask: each new chat gets its own worktree, and its work comes back into yours.
`codev_read_workspace_file`	Reads a file from the main checkout or a worktree.
`codev_search_workspace`	Finds lines containing some text.
`codev_workspace_changes`	Shows `git status` and `git diff`.
`codev_write_workspace_file`	Saves a file. It's refused if someone changed the file since your agent read it.
`codev_workspace_git`	Stages, commits, pushes, opens a pull request or merges a worktree into main.
`codev_run_command`	Runs a command in a new terminal of the workspace and returns its output. Teammates see the terminal while it runs.

A stopped workspace starts on its own when your agent uses a tool that runs on it: asking its agent, files, Git, commands or shipping. If it's still starting after about 40 seconds, the tool says so and your agent calls it again.

In a workspace with live main, codev_live_main shows everyone's work and where it stands, codev_mark_ready marks your own work ready, and codev_ship ships everything ready or only yours. See Live main and shipping.

Rooms tools (open_codev, codev_read_room, codev_post, codev_share_answer) open your Rooms and post in them.

Workspace Library

Each workspace has a Library: apps, slides, quizzes, guides and other pages your team made with Claude or ChatGPT, saved where everyone in the workspace can open them without anyone sending a link. When Claude or ChatGPT makes you one with CoDev connected, it also saves it to your workspace's Library (codev_save_page). If you have more than one workspace, it asks which one. Ask it to keep something to yourself and it won't save it.

Open Library from the workspace's top bar, or the Library tab beside Files and Browser. Each item shows who changed it last and when, and opens right there in the workspace; widen it, or open it full screen in a new tab. When your AI improves something it saved, it saves over the same item, so its link always shows the newest version. Editors and owners can save and delete items; viewers can open them. A workspace holds up to 200 items of up to 1 MB each.

Skills

The Library also holds your team's agent skills: a SKILL.md that teaches Claude Code or Codex how your team does something (writing release notes, running your deploy, reviewing a migration). Ask Claude or ChatGPT to save a skill it wrote or improved (codev_save_skill), or save one from a terminal with codev skills save. A skill is named by the name in its frontmatter, so saving the same name again updates it for everyone.

Open a skill under Skills in the Library to read what it does and its instructions. Copy install prompt gives you a prompt for Claude Code or Codex: your agent shows you what the skill does, then installs it into its skills folder once you say yes (codev skills install). Start a new session to load it. A skill is a teammate's instructions your agent will follow, so install only ones you trust. A workspace holds up to 200 skills of up to 100 KB each.

Your AI can also list a workspace's Library (codev_list_pages) read a skill (codev_read_skill), and delete an item you ask it to (codev_delete_page, codev_delete_skill). From a terminal, codev pages and codev skills do the same (CLI).

Library items run in a locked-down frame: one can load scripts, styles and data from the web, but it can't see your CoDev account, read your cookies or act as you.

Watch a workspace live

In an app that shows connector panels, such as Codex, ChatGPT or Claude, ask your agent to open your CoDev workspace (open_codev_workspace). The panel lists the workspace's agent chats, yours and your teammates', and shows the open chat live: each message, the steps its agent took (commands and edited files), and what a working agent is doing right now. Type in the panel to message that workspace's agent. A stopped workspace shows Start it. A workspace with live main adds a read-only Live main tab. The panel stops refreshing after 5 minutes without use (15 while the agent is working) and shows Paused while idle; click it to pick up where it left off.

After joining, Claude Code and Codex suggest working on your computer when the workspace allows it: your agent clones the workspace's repository (codev clone <workspace>), asks whether to link that folder, and links it on your yes, so from then on it edits that folder while your work shows in the workspace as your own worktree (CLI). In a workspace without live main, everyone edits the same checkout, so your agent checks the workspace's changes before editing.

File, Git, terminal and agent tools start a sleeping workspace on their own, as described above.

Your chat in CoDev

Once Claude Code or Codex uses one of a workspace's tools, its conversation shows live in that workspace's chat list under the name it has in Claude Code or Codex: your prompts, its replies and the steps it took, with secrets redacted, so your team follows the same chat you're in. Ask your agent to "show this chat in CoDev" to add it before it touches anything (codev_show_chat_in_workspace). It stays off until you say yes: codev setup asks (an agent running setup for you asks you and passes --mirror on or off); codev mirror off stops it and codev mirror on starts it again.

You can also message that chat from CoDev, from your phone for example: once the agent finishes its turn, your computer resumes the session with your message (it has to be awake), and the reply shows in CoDev like any other. If the agent's window is still open, it won't show that turn; reopen the session with claude --resume or codex resume to see it.

Only you can message it, since it runs on your computer. Your teammates see the chat as it goes, and fork it to carry on themselves: Continue in this workspace copies its messages into a new chat of their own for the workspace's agent, and Continue on my computer copies a prompt for their own Claude Code or Codex, which reads the chat through CoDev and picks the work up there. Your chat and your computer are unchanged either way.

Hand a session to a teammate

Out of usage, or done for the day? Hand your session, with your work in progress, to a teammate who edits the same workspace. They pick it up with the whole conversation, every prompt, reply and tool step, not a summary, on their own Claude or ChatGPT account. In your chat in CoDev, choose Hand off to a teammate… and pick who; it copies the command to run in the session's folder (or ask your agent to run it). When your agent stops because you're out of usage, the chat offers this first. You can also run it yourself:

codev handoff --to <their GitHub login>

Your uncommitted and untracked changes go to a hidden ref on your repository's origin (never a branch; never ignored files, .env files or keys), and the conversation goes to CoDev with secrets redacted, where only you and your teammate can read it. Your chat in CoDev stops updating and taking messages. They get an email, and your chat, and Handed to you in the Team panel (beside the Board, or under the bar at the top of the right-hand panel), show them two ways to continue:

Continue on my computer copies codev continue <id>. Run in their checkout of the repository (or anywhere, to clone it), it checks your work out on a new branch named after yours, with your uncommitted changes still uncommitted, and opens your session in their own Claude Code or Codex. Their chat in CoDev carries on from where yours stopped.
Continue in this workspace brings your work into a worktree of their own and opens a chat whose agent resumes your session.

Both of you need the same agent: a Claude Code session continues in Claude, a Codex session in Codex. Until they continue it, codev handoff --cancel <id> (or Take it back in the chat) gives it back to you; offers last seven days.

Coordinate with teammates' agents

While your agent works, it hears what the other agents on your repository are changing: whose agent it is, which agent, whether it runs on a laptop or in a CoDev workspace, its branch, and a few of its files. Each is told once, and again only when its files change. When their work and your agent's would conflict, CoDev test-merges the two and tells your agent which function conflicts and to fix it now, while it's small. It covers your own other checkouts and your teammates: people you share a CoDev workspace or a CoDev team with, on their machines or in their own workspaces. Any Git host works, and the repository doesn't need a CoDev workspace.

Install the CLI and sign in: npm install -g @trycodev/cli, then codev login.
Run codev setup, which adds the hook to every agent on your machine (Claude Code and Codex get it in the codev plugin), or print the hook settings for Codex or Cursor and merge them into the file it names:

codev coordinate setup codex

Use cursor instead of codex for Cursor. Codex runs plugin hooks only after you trust them: open /hooks and review CoDev. Changed hooks require review again. Disabling or removing the plugin turns off its connector and hooks together. The hook names Node and the CLI by their full paths, so it runs even when your agent's PATH lacks npm's global folder; run codev setup again after reinstalling either.

To test-merge work that isn't pushed yet, the CLI pushes a snapshot of your agent's work, uncommitted changes included, to a hidden ref on your own origin (refs/codev/wip/…, never a branch) while a teammate's agent is changing the same files, at most every 30 seconds. It deletes the ref when a Claude Code or Cursor session ends, or once it has gone 20 minutes without an update. Your teammate's CLI fetches it from that same remote into a scratch store, never your checkout's index, branches or objects, and test-merges it with their work; a conflict found on either side reaches both agents. Your code goes only between your machine and your Git host, never through CoDev. In a CoDev workspace, CoDev pushes an agent's work the same way with the GitHub connection of the member who started it.

Your agent is also told when its work, uncommitted changes included, would conflict with what has already merged into your repository's default branch on origin, such as a teammate's pull request. That check runs on your machine, fetching only the default branch at most every five minutes, and works without codev login.

The hook never slows your agent down: it answers from what it last saved and checks for changes in the background, at most every 10 seconds. An agent with nobody else on its repository hears nothing, so it costs no extra tokens; otherwise each line costs about 30 tokens. CoDev sees only file paths, function names, branch and ref names, never file contents.

#Connect

#Claude Code

#Codex

#ChatGPT and Claude

#What your agent can do

#Workspace Library

#Skills

#Watch a workspace live

#Your chat in CoDev

#Hand a session to a teammate

#Coordinate with teammates' agents