Your first session

By the end of this page you will have run Woopcode in a real repository, read its answer to a question about your own code, and applied one edit through the diff review.

This page assumes Woopcode is installed and a provider is connected. One command confirms both:

woopcode providers list

Start it in a repository#

Woopcode reads the directory it is launched from, so this is the step that decides what it can see:

cd path/to/your-projectwoopcode

Ask it something first#

Start with a question rather than a change. It costs nothing, it shows you how the agent moves through your repository, and it tells you whether it has understood the codebase before you let it edit anything.

Explain how authentication is structured in this repository.

Woopcode streams its work as it goes. You will see tool calls appear as they run — reading a file, grepping for a symbol, listing a directory — and then the answer builds underneath them. Nothing in that sequence writes to disk; every tool used to answer a question is read-only.

Make one change#

Now ask for something small and specific:

Add a docstring to the login handler explaining what it returns.

When the agent is ready to change an existing file, it stops. It does not write and then tell you. It shows the edit as a unified diff and waits:

 ← Editing  src/auth/login.ts                        +6 −0    export async function login(req: Request) {+    /**+     * Exchanges a set of credentials for a session cookie.+     *+     * Returns 401 with an empty body when the password+     * does not match; never reveals if the account exists.+     */     const body = await req.json();  Esc reject · ↑↓ scroll                    Enter apply

Press Enter to apply the edit, or Esc to reject it. Rejecting is not an error — the agent is told the edit was declined and carries on from there, so you can reject a diff and immediately explain what you wanted instead.

That pause is the part of Woopcode worth understanding properly. It applies to every edit to an existing file, and it is not the same mechanism that governs shell commands. Those are controlled separately — see Approval modes before you run anything that builds or tests.

What to do next in the same session#

A few commands are worth knowing on day one:

Your conversation is saved after every turn, so nothing is lost when you quit. Starting Woopcode again opens a fresh session rather than reopening it — woopcode --continue goes back to the newest one, and /resume picks from a list. /new starts a fresh one without leaving the session you are in.

Sessions belong to the project they happened in, so a repository only ever shows you its own. See Sessions & history.

When it does not work#

Path escapes the workspace: ../other-project/file.ts — The agent tried to reach outside the directory you launched it in. Woopcode resolves every path against the workspace root and refuses anything above it, symlinks included. Restart it inside the directory you actually want it to work on.

The agent answers about the wrong project — Check /workspace. Woopcode uses the directory it was launched from, not the one your editor has open.

A shell command you expected to run stopped and asked — That is the approval mode doing its job. The default runs reads and tests without asking and stops before anything that writes.

Trouble before you get this far is covered where it belongs: Install for bun: command not found, Connect a provider for a rejected API key.

Next#

• Approval modes — decide how much runs without asking, and understand what full-auto gives up.
• Reviewing diffs — scrolling long diffs, and what happens to a rejected edit.
• Tools — the 19 tools the agent can call, and which of them can change your files.

Added in woopcode@0.6.0