Get to a working change.

Install Harness, connect a model, open your project, and describe the outcome you want. This guide covers the everyday workflow and the tools available when you need more control.

01 Install 02 Connect a model 03 Give it a task

01 / Get started

Install Harness

Run the command for your system. The installer puts harness in your user directory and adds it to your PATH. Open a new terminal if the command is not found afterward.

curl -fsSL https://harness.neblume.com/install.sh | sh

Official builds support Linux amd64, arm64, and riscv64; macOS amd64 and arm64; and Windows amd64 and arm64.

02 / Set up

Open your project

In a terminal, go to the project directory and start Harness. Harness works in the directory you start it from. Run harness again in another terminal for another window, in the same project or another one.

cd path/to/your/project
harness

Open the command palette with Ctrl+O (or type / in an empty prompt), choose Accounts & servers, and add an account: a ChatGPT or Google AI subscription, or an OpenAI, Anthropic, or Gemini API key. A Parallel API key adds better web search and page reading. You can add several, and custom OpenAI- or Anthropic-compatible servers by address. Their order is your priority when more than one offers a model. Then choose Model to pick from every model your accounts and servers offer.

Settings live in ~/.harness/config.json, which you can also edit by hand. All windows connect to one local Harness server and share chats, tasks, settings, and logins.

03 / Start working

Give it a concrete task

Describe the result and any checks you expect. Press Enter to send; use Shift+Enter for another line.

Drafts disappear when the connection drops. Find the cause,
fix it, and add a test for failed saves.

Harness can inspect files, search the codebase, make edits, run commands and tests, and report what changed. Tool activity appears in the transcript, and each agent or background command shows as a line you can open, so you can review the work. Check the resulting diff before you keep it.

04 / Capabilities by goal

What you can do

Understand a codebase

Ask where a feature lives or how a flow works. Harness searches and reads project files; Finder can trace the relevant code paths.

Change or fix code

Describe a bug, feature, or refactor. Harness edits files in the shared workspace and can run build commands and tests. Ask it to include a test or explain its changes.

Research and reason

Ask for outside information when the task needs it. Librarian can research the web or GitHub; Oracle can examine a hard question with its own model and reasoning setting.

Check the result

Ask Harness to run the relevant checks or review a change. A separate agent can review the change independently. Test output and tool results stay visible in the transcript.

Handle larger tasks

Harness can start focused workers for separate pieces of work. They run in the background, share the same project files, and appear in the Tasks popup (Ctrl+T), where you can read their transcripts and message them.

05 / Work with a thread

Everyday workflow

Continue or steer

Send a follow-up after the answer to keep working in the same thread. While Harness is working, send a message to steer the current task. Press Esc twice or choose Cancel active to stop the current turn; agents and commands keep running until you stop them with /stop or from the Tasks popup. If a run was stopped, interrupted, or failed, press Enter on an empty prompt (or use /continue) to pick it up where it stopped.

Ask without interrupting

Choose Ask side question or enter /btw for a short answer using the current conversation. It opens above the prompt, so the conversation stays visible, and it does not change the main thread or use tools.

Find and revisit work

Use New conversation for a fresh task and Switch thread to return to a previous one. The switcher shows chats from the current directory; press Ctrl+A to see every directory. Opening a chat from another directory lets you move it here or use this directory just once. Search past prompts with Ctrl+R. You can remove an inactive thread from the switcher with Delete and a second confirmation.

Inspect and copy

Open a tool row to see its output, or an agent or command line to see its transcript or output. Scroll the transcript with the mouse or PgUp/PgDown; select text to copy it. In the terminal, Ctrl+G opens your draft in $VISUAL or $EDITOR.

Leave and come back

/exit or Ctrl+C twice closes the window. Work keeps running in the background after the window closes, even the last one; reopen Harness and switch to the thread to see it. If the server stopped while work was running, use /continue to resume the interrupted run.

06 / Make it yours

Models and settings

Open the command palette to choose a Model and Reasoning level. Finder, Librarian, Task, and general agents use the root model. You can give Oracle a separate model and reasoning level, or set it to inherit the root choice.

Web search provider lets you use automatic routing (it shows which account it currently uses), Parallel, Google, OpenAI, or Anthropic. The palette also opens Accounts & servers and sends feedback. Settings for a running thread are locked until that run finishes.

07 / Project setup

Give Harness project guidance

Put instructions in an AGENTS.md at the workspace root. A nested AGENTS.md can give rules for its directory. Harness also reads your personal ~/.config/harness/AGENTS.md.

For reusable workflows, add a SKILL.md under .agents/skills/<name>/ in the project or under ~/.config/harness/skills/. Skills can expose extra tools through a sibling mcp.json. Ask Harness to use the skill by name when a task calls for it.

08 / Keep handy

Quick reference

Terminal commands

harness: Open Harness in the current directory.
harness update --check: Check for an update; use harness update to install it.
harness version: Show the installed version.
harness help: Show CLI usage.

Terminal controls

Ctrl+O / Alt+O / /: Open commands and settings.
?: Show keyboard shortcuts.
Enter / Shift+Enter: Send / add a line. Ctrl+J also adds a line.
Ctrl+R: Search prompt history.
Ctrl+G: Edit the draft in your editor.
Home / End: Jump to the start / latest output.
Ctrl+T / /tasks: Open the Tasks popup of running and finished agents and commands.
/switch / /cancel: Change thread / cancel the current turn.
/stop: Stop every agent and command of the thread.
/continue: Continue a stopped, interrupted, or failed run.
/compact [focus]: Summarize the conversation now to free context, keeping your recent messages.
/btw / /exit: Ask a side question / close the window.

Updates install when Harness starts while no work is running; they never interrupt it. If something fails, the diagnostic ID in the message matches an entry in ~/.harness/logs/server.log.