Work with agents / Local workspaces
Use workspaces with a coding agent
You do not want to create a workspace by hand for each agent session. Run src agent setup once, and Claude Code, OpenCode and the other agents make and close their own workspaces.
2 min read
You need src on your computer. See Set up your coding agent.
1. Run the setup once
src agent setup
2. Start your agent
Start your agent as usual. For Claude Code, start it in a worktree, for example claude --worktree fix-login. What each agent gets:
| Agent | What it gets |
|---|---|
| Claude Code | Each worktree of Claude Code is a workspace from HEAD. When you remove the worktree, src ws close saves a checkpoint and gives the folder to the pool. See The workspace hooks of Claude Code. |
| OpenCode | The tools src_ws_create, src_ws_exec, src_ws_diff, src_ws_checkpoint, src_ws_list and src_ws_close. OpenCode gets them after src auth login, with the transcript upload plugin. |
| Codex, Cursor and other agents | The source skill tells them to run src ws create <name>, to work in the folder that it prints or with src ws exec, and to run src ws close <name> at the end. |
The name of a Claude Code worktree becomes the workspace name. Each character that a workspace name cannot have becomes -, so feature/auth becomes feature-auth.
Done
Your agents work in their own workspaces, and your checkout does not change. To bring their work into your checkout, see Review and accept agent work.
Stop a dev server of your agent
Claude Code runs its own commands in the workspace, for example a dev server from its Bash tool. src ws does not own these processes, so src ws close does not stop them. To make close stop a dev server, start it with src ws exec:
src ws exec fix-login -- pnpm dev