From first open to first commit

Installing and the first run

Get it from the download page. On a Mac that is the .dmg — macOS 13 Ventura or newer, one installer for both Apple Silicon and Intel. On Linux it is a single .AppImage: download it, make it executable, and it runs.

Either way the app updates itself: a card appears when a new version is out, and it downloads, verifies, applies and restarts. You never fetch an installer twice.

The only thing you need afterwards is git. If you plan to use an agent, the CLI you already use (Claude Code, Codex, …) only has to be on your PATH — codeme installs nothing on your behalf and uses what is already there. Language servers, database clients and Docker follow the same rule.

There is no sign-in screen on first run. There is no account.

Coming from VS Code · IntelliJ

codeme does not replace your IDE. A worktree is an ordinary folder, so the IDE you use opens it as it is — do the big refactor there, and do only the part where several agents run and you read what they did here. Most of what your hands know comes with you.

• Shortcuts — the default is the IntelliJ layout. Set workbench.keymap to vscode for the VS Code one. Both were transcribed from the keymap files the two products actually ship, and both tables are under Shortcuts.
• A key that does not suit you — under Shortcuts in settings, press the chord you want for each command and it is recorded. If another command already has that key, you are told whose it is before anything is saved. It is all stored in one line, workbench.keybindings.
• Debug configurations — a .vscode/launch.json is read as it is. If you are writing a new one, its place is .codeme/launch.json.
• Language servers · formatters · linters — only the ones already installed. The formatter and linter the project declares run on save, and nothing runs if it declares none.

Opening a project

Open a folder from the project list at the top of the sidebar. CtrlR brings the recent list back. You can keep several projects open at once, and each project's worktrees stack underneath it.

The sidebar has two layouts to pick from (workbench.sidebar):

• two-rails — worktrees per project on the left, files on the right. This is the default.
• one-rail — projects, worktrees and files stack in one column on the left.

Whether the next launch returns to the last project is workbench.restoreLastProject.

Making a worktree

Make a worktree with ＋ on the project row. Give a new branch name and it makes that branch and the worktree together; pick a branch that already exists and it makes only the worktree.

Several worktrees side by side

With a dev server running in each worktree, the cards in the rail tell you how each one stands.

• Ports — the port of the server that worktree started sits on its card, like :5173, and opens straight from the card's ⋯ menu or its context menu.
• CI — the CI result of the PR opened from that branch shows as “✓ CI” · “✕ CI” · “… CI”. For now only GitHub PRs.
• Clashes — if a file would conflict on merging into origin/main, or another worktree is changing it too, the card carries a warning. It is measured again every minute and when you come back to the window (git 2.38 or later).
• Keeping ports apart — turn on git.worktreeShiftPorts and the ports in config files copied into a new worktree, like .env, are moved so they do not overlap another worktree's. It is off by default.

The dev server goes beside the code in a browser tab. Open one from the tab strip's ＋ menu or Open in the Ports panel; typing just 3000 in the address bar opens localhost. Devtools dock inside the same tab.

Reading a PR in the Review panel and spot something to fix? When an agent is running in that branch's worktree, every thread has Paste to agent, which hands it the comment as it is.

Attaching an agent

Pick an agent from the ＋ menu on the worktree card. That menu shows two things as separate items.

• Start fresh — opens an empty session.
• Resume — picks up the session that was running in that worktree.

What appears in that menu is decided by what is actually installed on this machine. To set it by hand, agents.offered is the list and terminal.agents is the command each entry runs.

Older conversations are under the agent's name in the same menu. Pick one of the past conversations Claude Code and Codex left in their own files and it resumes right there — the app only reads those files. The start screen's Pick up where you left off shows the five most recent first.

Whether a session that was running is picked up again on the next launch is agents.resumeOnRestart.

Whether an agent is running, or waiting on you, shows as a number in the menu bar. When the window is not in front, an OS notification says so instead — when it is in front the corner toast does that job, so the default is to send no notification.

Two things for when there are several branches going at once.

• Say it to several agents (⌘⌥⇧A) sends one instruction to the sessions you pick. You do not type “merge main” four times.
• Find in agent output (⌘⌥⇧F) searches across sessions. Which session said that was something you found by opening tabs one at a time.

Queued work and checks

Ctrl⌥Q is the queue. Write down the work before you step away, and each job gets a branch, a worktree and an agent of its own, run one at a time. You choose how each job runs.

• Run once and exit (the default) — the agent gives its answer and stops. You come back and read the result.
• Leave it open to watch — it stays open like an ordinary session, so you can step in midway.

Raise ways to 2 or more and the same instruction runs separately down as many as eight branches. Compare the finished ones, press Keep this one on one, and the worktrees and branches of the others are deleted. A way with uncommitted changes is not deleted but listed — deleting it anyway takes one more press.

When an agent stops, the checks run in its worktree. There is no config file to write — the typecheck and lint scripts in package.json, and the runners the test panel finds, are the list. Only those installed on this machine run, and they stop at the first one that goes red. Queued work always goes through them. To check ordinary sessions too, turn on agents.gate (off by default). To run them by hand, press Check on the worktree card.

What you are told while in another app is set by notify.events.

• waiting — an agent is waiting for your answer.
• finished — an agent has finished its work. Off by default.
• review — a review was requested of you.
• checks — checks an agent started went red. Green is not announced.
• mine — your pull request failed, had changes requested, or was approved. Each is said once.

Reading what is left

The usage chip in the status bar — or the tool bar — reports what is left, not what is spent. The question in front of it is "can I start something big now", and 30% left answers that while 70% used makes you do the subtraction first.

Hovering the chip opens a card with two rows.

• Session — the window you are spending from right now. This is the number on the chip.
• Weekly — the one that stops you for days rather than hours. It lives on the card only.

A ~ in front of the number means it was measured here rather than told to us by the server, and the bar is striped instead of solid. What it is measured against is the busiest window seen on this machine in the last few days; if you know your plan's real allowance, put it in agents.claudeWindowTokens · agents.claudeWeeklyTokens and that wins.

Turning the chip off, or moving it between the status bar and the tool bar, is agents.usage and agents.usagePlace.

Reading what changed

Ctrl⇧X opens the Agent changes panel: the files the agent touched on the left, the diff for the selected one on the right.

• The baseline is the moment the agent started. Edits you made before that are not mixed in.
• The folded lines between hunks open, down to "which function these three lines sit in".
• You can switch to a side-by-side view, and drag the boundary in the middle to widen one side.
• Bigger on a diff's header opens it in a dialog the size of the window — the history, commit and compare worktrees panels have the same button.
• Once you have read it, Mark reviewed moves the mark forward.

Two more to keep open beside it. Problems (⌘⇧M) gathers everything the language servers have said about this project into one list — which you used to learn by opening the file. Compare worktrees (Ctrl⌥C) puts two branches side by side and shows what differs. Which of two agents given the same job to keep is the question you ask in front of it.

Committing and pushing

Ctrl⇧G is the commit panel, Ctrl⇧H the history graph. Staging, committing and pushing are in one place, and pushing lives on the same screen as the commit — you do not go looking for somewhere to push once you have committed.

The history draws branches splitting and joining as they actually are. Measured on a repository of a hundred thousand commits.

Whether a pull merges or rebases is git.pullMode. When it conflicts, a view opens with both sides side by side and one hunk chosen at a time.

To neither throw away nor commit what you have changed, press Stash everything in the commit panel. New untracked files go with it, and the Stashed list below restores or drops it. Removing a worktree also offers Stash and remove.

In the history, a commit's Undo… asks one of four things. revert stacks one more commit that does the opposite, and reset takes the branch back to that commit as soft, mixed or hard. hard wipes the working tree too, so it asks once more. The Search commits box above the history (⌘F in the panel) finds anything in the whole history by sha, author, subject or branch name.

Local history

Every time the app saves a file, it keeps what was there before the save. git remembers only what was committed, so what this file was between two commits — before an agent overwrote it, before you deleted it — is only here.

• Ctrl⌥⇧H or Local history on the toolbar — a tree of the files that have history.
• The button in the editor's header, or the file tree's right-click menu — the versions of that one file.

Pick a version and you see its diff against the current content; Put this version back writes it back. What was on disk just before is kept as a version too, so a restore can itself be undone. If the file has unsaved edits, it does not restore and asks you to save first — those edits exist nowhere else.

Tests, builds, containers and databases

Whether the code the agent fixed is green, whether the build gets through, whether the service you need is up, and what the rows inside it look like — every one of those questions ended in a terminal. Four panels take them on.

The test panel and the build panel both show you the command they ran. When a result is surprising, that is what separates the app's opinion from the runner's output at a glance.

The build panel's task list is filled by asking Gradle itself. It is the answer to gradle tasks --all rather than a list written down here, so bootRun is there for a Spring project and absent for one that is not. Maven has no way of being asked, so its lifecycle is used. When a build fails, the compile errors come out separately as a list of lines, and pressing one opens that file at that line — scrolling four hundred lines to find three is what you did in a terminal. The list takes the arrow keys, and Return opens a row.

Debugging

⌘⇧D is the Run and Debug panel. It debugs Go, Python, Java, C, C++ and Rust, and like tests and builds it uses only the adapters already installed.

What to launch is looked for in this order — .codeme/launch.json, then .vscode/launch.json, for Rust the binaries and tests cargo reports, and finally the open file. Both launch.json files use VS Code's format, and where names clash .codeme wins. Only "request": "launch" is used — attaching to a process that is already running is not there yet.

Set a breakpoint by clicking the editor's margin (F9). Right-click to make it one of three — Stop only when, Stop only on this hit, Print instead of stopping (a logpoint). Breakpoints survive a restart, and nothing is written into the project folder. The panel has the call stack, variables, watches and Stop on exceptions.

F5 start or continue, ⇧F5 stop, F10 step over, F11 step into, ⇧F11 step out.

Connecting My work (optional)

Ctrl⇧Y opens My work. Review requests at the top, what you are on below. GitHub, Forgejo, Gitea, Bitbucket and Jira are read directly through each one's own API.

You connect by signing in from the browser. No going to the forge's settings to make a token, reading up on which permissions to tick, and copying it back. The forges ask different things of us, so there are three ways in.

• GitHub — you type a code into the browser once. Nothing passes through our servers.
• Forgejo and Gitea — they come back to an address on this computer. Again, nothing passes through us.
• Bitbucket and Jira — both of those are closed to us, so the site stands in for the single moment a token is exchanged. It sits encrypted for ten minutes, and the moment the app that started the sign-in collects it, it is deleted.

The token box has not gone anywhere — a self-hosted instance we have no registration with still shows you exactly that. A token that expires (two hours, for Bitbucket) is renewed once when a call is refused, and the call is made again.

• Tokens go into the OS credential store — the Keychain on a Mac, Credential Manager on Windows, Secret Service on Linux. However many places you sign in to, it is one entry, so the Keychain asks you once.
• The settings file keeps only the address. No IPC command hands a token back to the window.
• A connection you are not signed in to is not shown as a failure but as the address it called and a sign-in button.

Click a pull request and you either open it in the browser or make a worktree on its branch. If the branch is not on this machine, it is fetched and then made.

Tickets work the same way. A worktree made from a ticket takes its branch name from the work.branch template, and a pull request opened from that worktree has its description filled from the ticket. Send to agent puts the ticket into that worktree's agent input without sending it — adding a line and sending is yours to do.

The dashboard at the top of the panel says how far the current sprint has got and which tickets are blocked waiting on something. Open a ticket and its comments, history, subtasks, linked issues and attachments are read inside the app, and you can change the assignee. A pull request's row says whether its checks passed and whether it is approved. The board is kept on disk, so opening the window shows what was last read first.

Ctrl⌥Y is the Review panel. Pull requests that asked you for a review (GitHub and Forgejo) are read inside the app; add a comment to any line, and send it all at once with an overall note as Approve, Request changes or Comment. On your own pull request you can only comment.

Choosing how it looks

There is one theme. Pick it and the code and the window change together.

The sidebar and the toolbar are never painted in the theme's colours — the window keeps one fixed pair, and the theme only decides which of the two is on. To follow the system, pick a light theme in workbench.themeLight.

The rest of what sets the window's words and sizes: workbench.language (Korean · English), workbench.fontSize, editor.fontSize, workbench.keymap (IntelliJ · VS Code).

Shortcuts

The default is the IntelliJ layout; set workbench.keymap to vscode for the VS Code one. The same commands sit where that product keeps them — switch between the two tables below.

When you are stuck

Completion, hover and go-to-definition do nothing

That language's language server has to be installed on this machine — only whichever of rust-analyzer, gopls, clangd and pyright-langserver is already there gets used. When one is missing the status bar says so. TypeScript and JavaScript are answered by the editor's own service, which is why they are not on the list.

The debugger does not start

The adapter for that language is missing. The panel names what is missing — dlv for Go, debugpy in the virtual environment for Python, lldb-dap for C, C++ and Rust. Java needs a plugin for its language server, and the panel shows the command that fetches it.

The database panel refuses to connect

That engine's client is not installed. The panel names the command it looked for and could not find, so installing that is the whole fix.

The My work panel is empty

There is no token, or it has expired. It is shown as the address it called and a sign-in rather than as a failure, so start by checking that the address on that line is the right one.

The usage reads ~ and nothing firmer

It means no limit came back from the server: you are signed out, nothing has run yet in this window, or the network is blocked. The number you see then is an estimate measured on this machine.

The terminal draws broken characters

On a machine with no GPU renderer, the core works that out and falls back to the CPU renderer. If it still looks wrong, you can pick the renderer yourself in settings.

Anything else

Tell us through wherever you got the build. No diagnostic data is sent automatically, so what happened is only what you write down.