harnsy
Start free
EN

Getting started

Install harnsy and meet your first team. Pick your AI program and your computer, and the steps unfold one at a time.

Prefer to watch? A 33-minute video, from install to a finished site ↓

Or ask your AI program to do it

Paste this into your AI program. It reads a short guide written for agents, tells you what the install changes and waits for your yes.

Install harnsy following https://harnsy.dev/llms.txt

1. Install

Claude Code on Linux

Before you start (Anthropic’s pages, read 8 Nov 2026): Claude Code needs a Pro, Max, Ultra, Team, Enterprise or Console account; the free claude.ai plan does not include it; you must live in a country where Anthropic offers Claude Code; Ubuntu 20.04+/Debian 10+ (Alpine 3.19+), 4 GB of memory, internet. Links: Anthropic’s setup instructions, pricing, terminal guide. No prices are printed.

You sign in on the provider’s page. The code goes straight to the program on this computer, which keeps the login where it always does. harnsy does not read the login to use it and does not send it anywhere; it only asks the program whether you are signed in. Before it changes the program’s settings file, which can also hold your login, harnsy keeps a backup copy on this computer (see Keys, logins and connections).

  1. Open a terminal

    A terminal is a window where you type commands. Linux: open your terminal app. The installers do not ask for administrator rights.

    You see: a window with a blinking cursor.

  2. Create your Claude account and choose a plan

    In your browser go to claude.ai, create an account, and choose a plan that includes Claude Code on Anthropic’s pricing page; pay for it there.

    You see: you are signed in on claude.ai.

  3. Install Claude Code

    Anthropic’s command (not harnsy’s; you can read the script first by opening the address in a browser).

    Shell
    curl -fsSL https://claude.ai/install.sh | bash

    You see: nothing moves while it downloads. On Alpine or without curl/bash, Anthropic’s page has the extra packages.

  4. Check it

    Open a new terminal and run claude --version.

    You see: a version number. If claude is not found, the install folder is not on your PATH: Anthropic’s setup page has the fix.

  5. Sign in

    Run claude in any folder, follow the browser prompts, sign in with your Claude account, then close it (Ctrl+C twice).

    You see: Claude Code asks you to log in, then opens.

  6. Install harnsy

    You can do this in two ways. Both lead to the same installer.

    Way A: ask your AI program. Open it (type claude, or codex) and tell it:

    Read https://harnsy.dev/llms.txt and help me install and set up harnsy.

    It reads a short guide written for agents. Before it installs, it tells you what the install changes (the settings files of Claude Code and Codex: hooks and an “allow harnsy” entry so agents can call harnsy without asking each time, in all your Claude Code sessions on this computer; a backup is kept) and waits for your yes. Then it installs harnsy for you. If your AI program may not run the downloaded installer, it asks you to run the command yourself, in your own terminal; it is the same command as in Way B, and it asks you nothing. Do not look for another way around that: it is your AI program’s own safeguard. Then it checks that harnsy runs and asks you one question, with buttons: which folder to start from. It sets up your company and your first project, opens your lead, and opens the browser on your chat with the lead.

    Way B: type the command. You can read the script before you run it: open https://harnsy.dev/install.sh in your browser. This dry run changes nothing; it shows what the installer would do:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --dry-run

    You see: every step the installer would take. Nothing is written.

    Now install. On a computer that never had harnsy, add --first-run:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --first-run

    You see: with --first-run the installer asks you nothing. It says yes in advance to harnsy’s own set: agents may open in their own windows, each new agent gets a short note about harnsy, you can answer agents’ questions from the browser, and agents can talk to harnsy without asking each time. That changes settings files of Claude Code and Codex (hooks); each change is shown, and a backup is kept. It sets up no tray icon and no status line. At the end it prints “What changed on this computer” and how to undo it (harnsy uninstall). On a computer that already had harnsy (also one where it was uninstalled, which keeps its data), --first-run is ignored and the installer asks as usual.

    Check that it runs. Open http://127.0.0.1:7788 in your browser.

    You see: the harnsy dashboard. On a computer that has no company yet, it starts with “Choose your language”: that is the first run, next.

    Your agents run in tmux if it is installed (3.1 or newer), and otherwise in harnsy’s own terminal host; you install nothing, and the dashboard shows each agent live. --first-run picks it for you without a question; a normal install asks once and keeps your answer.

Claude Code on macOS

Before you start (Anthropic’s pages, read 8 Nov 2026): Claude Code needs a Pro, Max, Ultra, Team, Enterprise or Console account; the free claude.ai plan does not include it; you must live in a country where Anthropic offers Claude Code; macOS 13+, 4 GB of memory, internet. Links: Anthropic’s setup instructions, pricing, terminal guide. No prices are printed.

You sign in on the provider’s page. The code goes straight to the program on this computer, which keeps the login where it always does. harnsy does not read the login to use it and does not send it anywhere; it only asks the program whether you are signed in. Before it changes the program’s settings file, which can also hold your login, harnsy keeps a backup copy on this computer (see Keys, logins and connections).

  1. Open a terminal

    A terminal is a window where you type commands. macOS: open Terminal (Applications › Utilities › Terminal). The installers do not ask for administrator rights.

    You see: a window with a blinking cursor.

  2. Create your Claude account and choose a plan

    In your browser go to claude.ai, create an account, and choose a plan that includes Claude Code on Anthropic’s pricing page; pay for it there.

    You see: you are signed in on claude.ai.

  3. Install Claude Code

    Anthropic’s command (not harnsy’s; you can read the script first by opening the address in a browser).

    Shell
    curl -fsSL https://claude.ai/install.sh | bash

    If you already use Homebrew, you can run this instead (needs macOS 13 or newer; also Anthropic’s command; Homebrew installs do not update themselves: Anthropic’s page says how to upgrade):

    Shell
    brew install --cask claude-code

    You see: nothing moves while it downloads. On Alpine or without curl/bash, Anthropic’s page has the extra packages.

  4. Check it

    Open a new terminal and run claude --version.

    You see: a version number. If claude is not found, the install folder is not on your PATH: Anthropic’s setup page has the fix.

  5. Sign in

    Run claude in any folder, follow the browser prompts, sign in with your Claude account, then close it (Ctrl+C twice).

    You see: Claude Code asks you to log in, then opens.

  6. Install harnsy

    You can do this in two ways. Both lead to the same installer.

    Way A: ask your AI program. Open it (type claude, or codex) and tell it:

    Read https://harnsy.dev/llms.txt and help me install and set up harnsy.

    It reads a short guide written for agents. Before it installs, it tells you what the install changes (the settings files of Claude Code and Codex: hooks and an “allow harnsy” entry so agents can call harnsy without asking each time, in all your Claude Code sessions on this computer; a backup is kept) and waits for your yes. Then it installs harnsy for you. If your AI program may not run the downloaded installer, it asks you to run the command yourself, in your own terminal; it is the same command as in Way B, and it asks you nothing. Do not look for another way around that: it is your AI program’s own safeguard. Then it checks that harnsy runs and asks you one question, with buttons: which folder to start from. It sets up your company and your first project, opens your lead, and opens the browser on your chat with the lead.

    Way B: type the command. You can read the script before you run it: open https://harnsy.dev/install.sh in your browser. This dry run changes nothing; it shows what the installer would do:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --dry-run

    You see: every step the installer would take. Nothing is written.

    Now install. On a computer that never had harnsy, add --first-run:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --first-run

    You see: with --first-run the installer asks you nothing. It says yes in advance to harnsy’s own set: agents may open in their own windows, each new agent gets a short note about harnsy, you can answer agents’ questions from the browser, and agents can talk to harnsy without asking each time. That changes settings files of Claude Code and Codex (hooks); each change is shown, and a backup is kept. It sets up no tray icon and no status line. At the end it prints “What changed on this computer” and how to undo it (harnsy uninstall). On a computer that already had harnsy (also one where it was uninstalled, which keeps its data), --first-run is ignored and the installer asks as usual.

    Check that it runs. Open http://127.0.0.1:7788 in your browser.

    You see: the harnsy dashboard. On a computer that has no company yet, it starts with “Choose your language”: that is the first run, next.

    Your agents run in tmux if it is installed (3.1 or newer), and otherwise in harnsy’s own terminal host; you install nothing, and the dashboard shows each agent live. --first-run picks it for you without a question; a normal install asks once and keeps your answer.

Claude Code on Windows

Before you start (Anthropic’s pages, read 8 Nov 2026): Claude Code needs a Pro, Max, Ultra, Team, Enterprise or Console account; the free claude.ai plan does not include it; you must live in a country where Anthropic offers Claude Code; Windows 10 1809+, 4 GB of memory, internet. Links: Anthropic’s setup instructions, pricing, terminal guide. No prices are printed.

You sign in on the provider’s page. The code goes straight to the program on this computer, which keeps the login where it always does. harnsy does not read the login to use it and does not send it anywhere; it only asks the program whether you are signed in. Before it changes the program’s settings file, which can also hold your login, harnsy keeps a backup copy on this computer (see Keys, logins and connections).

  1. Open a terminal

    A terminal is a window where you type commands. Windows: open PowerShell (Start menu, type “PowerShell”) (not CMD: the prompt shows PS C:\). The installers do not ask for administrator rights.

    You see: a window with a blinking cursor.

  2. Create your Claude account and choose a plan

    In your browser go to claude.ai, create an account, and choose a plan that includes Claude Code on Anthropic’s pricing page; pay for it there.

    You see: you are signed in on claude.ai.

  3. Install Claude Code

    Anthropic’s command; it needs Windows 10 1809 or newer and no administrator rights; Git for Windows is optional and only adds a Bash tool for Claude Code.

    PowerShell
    irm https://claude.ai/install.ps1 | iex

    You see: nothing moves while it downloads. If PowerShell says The token '&&' is not a valid statement separator you are in PowerShell, which is right for this command; if it says 'irm' is not recognized, you are in CMD: open PowerShell.

  4. Check it

    Open a new PowerShell and run claude --version.

    You see: a version number. If claude is not found, the install folder is not on your PATH: Anthropic’s setup page has the fix.

  5. Sign in

    Run claude in any folder, follow the browser prompts, sign in with your Claude account, then close it (Ctrl+C twice).

    You see: Claude Code asks you to log in, then opens.

  6. Install harnsy

    You can do this in two ways. Both lead to the same installer.

    Way A: ask your AI program. Open it (type claude, or codex) and tell it:

    Read https://harnsy.dev/llms.txt and help me install and set up harnsy.

    It reads a short guide written for agents. Before it installs, it tells you what the install changes (the settings files of Claude Code and Codex: hooks and an “allow harnsy” entry so agents can call harnsy without asking each time, in all your Claude Code sessions on this computer; a backup is kept) and waits for your yes. Then it installs harnsy for you. If your AI program may not run the downloaded installer, it asks you to run the command yourself, in your own terminal; it is the same command as in Way B, and it asks you nothing. Do not look for another way around that: it is your AI program’s own safeguard. Then it checks that harnsy runs and asks you one question, with buttons: which folder to start from. It sets up your company and your first project, opens your lead, and opens the browser on your chat with the lead.

    Way B: type the command. You can read the script before you run it: open https://harnsy.dev/install.ps1 in your browser. This dry run changes nothing; it shows what the installer would do:

    PowerShell
    $env:HARNSY_INSTALL_ARGS = "--dry-run"; irm https://harnsy.dev/install.ps1 | iex

    You see: every step the installer would take. Nothing is written.

    Now install. On a computer that never had harnsy, add --first-run:

    PowerShell
    $env:HARNSY_INSTALL_ARGS = "--first-run"; irm https://harnsy.dev/install.ps1 | iex

    You see: with --first-run the installer asks you nothing. It says yes in advance to harnsy’s own set: agents may open in their own windows, each new agent gets a short note about harnsy, you can answer agents’ questions from the browser, and agents can talk to harnsy without asking each time. That changes settings files of Claude Code and Codex (hooks); each change is shown, and a backup is kept. It sets up no tray icon and no status line. At the end it prints “What changed on this computer” and how to undo it (harnsy uninstall). On a computer that already had harnsy (also one where it was uninstalled, which keeps its data), --first-run is ignored and the installer asks as usual.

    Check that it runs. Open http://127.0.0.1:7788 in your browser.

    You see: the harnsy dashboard. On a computer that has no company yet, it starts with “Choose your language”: that is the first run, next.

    Your agents run in harnsy’s own terminal host (ConPTY); you install nothing, and the dashboard shows each agent live. --first-run picks it for you without a question; a normal install asks once and keeps your answer.

Codex on Linux

Before you start (OpenAI’s pages, read 8 Nov 2026): OpenAI’s pricing page says Codex is included in the ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise plans (features differ by plan; usage limits apply), and that you can instead pay by API usage with an API key. Links: Codex CLI, pricing, sign-in options. No prices are printed. You also need to live in a country where OpenAI offers ChatGPT and Codex (see OpenAI’s pages for the list).

You sign in on the provider’s page. The code goes straight to the program on this computer, which keeps the login where it always does. harnsy does not read the login to use it and does not send it anywhere; it only asks the program whether you are signed in. Before it changes the program’s settings file, which can also hold your login, harnsy keeps a backup copy on this computer (see Keys, logins and connections).

  1. Open a terminal

    A terminal is a window where you type commands. Linux: open your terminal app. The installers do not ask for administrator rights.

    You see: a window with a blinking cursor.

  2. Get a ChatGPT account on a plan that includes Codex

    In your browser go to chatgpt.com, create an account if you have none, and pick a plan from OpenAI’s pricing page (Codex is included in Free, Go, Plus, Pro, Business, Edu and Enterprise; usage limits apply). Or use an API key instead and pay by API usage (OpenAI’s pricing page). An API key is a secret: keep it in your own environment (for example OPENAI_API_KEY); do not put it in a prompt, a file or a message to an agent, and do not paste it into harnsy.

    You see: you are signed in on chatgpt.com.

  3. Install Codex

    OpenAI’s command (not harnsy’s; you can read the script first by opening the address in a browser):

    Shell
    curl -fsSL https://chatgpt.com/codex/install.sh | sh

    OpenAI’s page also has tabs for npm and Homebrew; read them there.

    You see: the installer finishes and codex can be started in a new terminal.

  4. Sign in

    In a project folder run codex. On the first run choose “Sign in with ChatGPT” and finish in the browser. On a machine without a browser, OpenAI recommends codex login --device-auth (a beta; you type a code on OpenAI’s page). With an API key: printenv OPENAI_API_KEY | codex login --with-api-key. To check: codex login status.

    You see: a browser page to sign in, then Codex opens. Close it when you are in.

  5. Install harnsy

    The “ask your AI program” route is written for Claude Code; it has not been tried with Codex. If you use it and Codex asks you to approve a command, read the command first.

    Way B: type the command. You can read the script before you run it: open https://harnsy.dev/install.sh in your browser. This dry run changes nothing; it shows what the installer would do:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --dry-run

    You see: every step the installer would take. Nothing is written.

    Now install. On a computer that never had harnsy, add --first-run:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --first-run

    You see: with --first-run the installer asks you nothing. It says yes in advance to harnsy’s own set: agents may open in their own windows, each new agent gets a short note about harnsy, you can answer agents’ questions from the browser, and agents can talk to harnsy without asking each time. That changes settings files of Claude Code and Codex (hooks); each change is shown, and a backup is kept. It sets up no tray icon and no status line. At the end it prints “What changed on this computer” and how to undo it (harnsy uninstall). On a computer that already had harnsy (also one where it was uninstalled, which keeps its data), --first-run is ignored and the installer asks as usual.

    Check that it runs. Open http://127.0.0.1:7788 in your browser.

    You see: the harnsy dashboard. On a computer that has no company yet, it starts with “Choose your language”: that is the first run, next.

    Your agents run in tmux if it is installed (3.1 or newer), and otherwise in harnsy’s own terminal host; you install nothing, and the dashboard shows each agent live. --first-run picks it for you without a question; a normal install asks once and keeps your answer.

Codex on macOS

Before you start (OpenAI’s pages, read 8 Nov 2026): OpenAI’s pricing page says Codex is included in the ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise plans (features differ by plan; usage limits apply), and that you can instead pay by API usage with an API key. Links: Codex CLI, pricing, sign-in options. No prices are printed. You also need to live in a country where OpenAI offers ChatGPT and Codex (see OpenAI’s pages for the list).

You sign in on the provider’s page. The code goes straight to the program on this computer, which keeps the login where it always does. harnsy does not read the login to use it and does not send it anywhere; it only asks the program whether you are signed in. Before it changes the program’s settings file, which can also hold your login, harnsy keeps a backup copy on this computer (see Keys, logins and connections).

  1. Open a terminal

    A terminal is a window where you type commands. macOS: open Terminal (Applications › Utilities › Terminal). The installers do not ask for administrator rights.

    You see: a window with a blinking cursor.

  2. Get a ChatGPT account on a plan that includes Codex

    In your browser go to chatgpt.com, create an account if you have none, and pick a plan from OpenAI’s pricing page (Codex is included in Free, Go, Plus, Pro, Business, Edu and Enterprise; usage limits apply). Or use an API key instead and pay by API usage (OpenAI’s pricing page). An API key is a secret: keep it in your own environment (for example OPENAI_API_KEY); do not put it in a prompt, a file or a message to an agent, and do not paste it into harnsy.

    You see: you are signed in on chatgpt.com.

  3. Install Codex

    OpenAI’s command (not harnsy’s; you can read the script first by opening the address in a browser):

    Shell
    curl -fsSL https://chatgpt.com/codex/install.sh | sh

    OpenAI’s page also has tabs for npm and Homebrew; read them there.

    You see: the installer finishes and codex can be started in a new terminal.

  4. Sign in

    In a project folder run codex. On the first run choose “Sign in with ChatGPT” and finish in the browser. On a machine without a browser, OpenAI recommends codex login --device-auth (a beta; you type a code on OpenAI’s page). With an API key: printenv OPENAI_API_KEY | codex login --with-api-key. To check: codex login status.

    You see: a browser page to sign in, then Codex opens. Close it when you are in.

  5. Install harnsy

    The “ask your AI program” route is written for Claude Code; it has not been tried with Codex. If you use it and Codex asks you to approve a command, read the command first.

    Way B: type the command. You can read the script before you run it: open https://harnsy.dev/install.sh in your browser. This dry run changes nothing; it shows what the installer would do:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --dry-run

    You see: every step the installer would take. Nothing is written.

    Now install. On a computer that never had harnsy, add --first-run:

    Shell
    curl -fsSL https://harnsy.dev/install.sh | sh -s -- --first-run

    You see: with --first-run the installer asks you nothing. It says yes in advance to harnsy’s own set: agents may open in their own windows, each new agent gets a short note about harnsy, you can answer agents’ questions from the browser, and agents can talk to harnsy without asking each time. That changes settings files of Claude Code and Codex (hooks); each change is shown, and a backup is kept. It sets up no tray icon and no status line. At the end it prints “What changed on this computer” and how to undo it (harnsy uninstall). On a computer that already had harnsy (also one where it was uninstalled, which keeps its data), --first-run is ignored and the installer asks as usual.

    Check that it runs. Open http://127.0.0.1:7788 in your browser.

    You see: the harnsy dashboard. On a computer that has no company yet, it starts with “Choose your language”: that is the first run, next.

    Your agents run in tmux if it is installed (3.1 or newer), and otherwise in harnsy’s own terminal host; you install nothing, and the dashboard shows each agent live. --first-run picks it for you without a question; a normal install asks once and keeps your answer.

Codex on Windows

Before you start (OpenAI’s pages, read 8 Nov 2026): OpenAI’s pricing page says Codex is included in the ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise plans (features differ by plan; usage limits apply), and that you can instead pay by API usage with an API key. Links: Codex CLI, pricing, sign-in options. No prices are printed. You also need to live in a country where OpenAI offers ChatGPT and Codex (see OpenAI’s pages for the list).

You sign in on the provider’s page. The code goes straight to the program on this computer, which keeps the login where it always does. harnsy does not read the login to use it and does not send it anywhere; it only asks the program whether you are signed in. Before it changes the program’s settings file, which can also hold your login, harnsy keeps a backup copy on this computer (see Keys, logins and connections).

  1. Open a terminal

    A terminal is a window where you type commands. Windows: open PowerShell (Start menu, type “PowerShell”) (not CMD: the prompt shows PS C:\). The installers do not ask for administrator rights.

    You see: a window with a blinking cursor.

  2. Get a ChatGPT account on a plan that includes Codex

    In your browser go to chatgpt.com, create an account if you have none, and pick a plan from OpenAI’s pricing page (Codex is included in Free, Go, Plus, Pro, Business, Edu and Enterprise; usage limits apply). Or use an API key instead and pay by API usage (OpenAI’s pricing page). An API key is a secret: keep it in your own environment (for example OPENAI_API_KEY); do not put it in a prompt, a file or a message to an agent, and do not paste it into harnsy.

    You see: you are signed in on chatgpt.com.

  3. Install Codex

    Install Codex on Windows itself, following the Windows tab of OpenAI’s Codex CLI page, so that codex works in PowerShell. Codex installed only inside WSL is not found by harnsy: it is a different PATH and a different home. (OpenAI documents the WSL route separately; it is for working inside WSL, not for this guide.)

  4. Sign in

    In a project folder run codex. On the first run choose “Sign in with ChatGPT” and finish in the browser. On a machine without a browser, OpenAI recommends codex login --device-auth (a beta; you type a code on OpenAI’s page). With an API key: printenv OPENAI_API_KEY | codex login --with-api-key. To check: codex login status.

    You see: a browser page to sign in, then Codex opens. Close it when you are in.

  5. Install harnsy

    The “ask your AI program” route is written for Claude Code; it has not been tried with Codex. If you use it and Codex asks you to approve a command, read the command first.

    Way B: type the command. You can read the script before you run it: open https://harnsy.dev/install.ps1 in your browser. This dry run changes nothing; it shows what the installer would do:

    PowerShell
    $env:HARNSY_INSTALL_ARGS = "--dry-run"; irm https://harnsy.dev/install.ps1 | iex

    You see: every step the installer would take. Nothing is written.

    Now install. On a computer that never had harnsy, add --first-run:

    PowerShell
    $env:HARNSY_INSTALL_ARGS = "--first-run"; irm https://harnsy.dev/install.ps1 | iex

    You see: with --first-run the installer asks you nothing. It says yes in advance to harnsy’s own set: agents may open in their own windows, each new agent gets a short note about harnsy, you can answer agents’ questions from the browser, and agents can talk to harnsy without asking each time. That changes settings files of Claude Code and Codex (hooks); each change is shown, and a backup is kept. It sets up no tray icon and no status line. At the end it prints “What changed on this computer” and how to undo it (harnsy uninstall). On a computer that already had harnsy (also one where it was uninstalled, which keeps its data), --first-run is ignored and the installer asks as usual.

    Check that it runs. Open http://127.0.0.1:7788 in your browser.

    You see: the harnsy dashboard. On a computer that has no company yet, it starts with “Choose your language”: that is the first run, next.

    Your agents run in harnsy’s own terminal host (ConPTY); you install nothing, and the dashboard shows each agent live. --first-run picks it for you without a question; a normal install asks once and keeps your answer.

The full guide · 33 min

From install to a working website, in one run.

One real run on a test machine: install harnsy, start a first project, hand tasks to your lead, hire a designer and get a finished small-business site. Use the chapters to jump to the part you need.

A real run, sped up. Generated voice, in English; captions are on by default, turn them off in the player. The customer and the work in the video are sample data.

2. First team

  1. Choose your language

    You see: “Choose your language.” Under it: English, Russian, Spanish, and a note “your browser's language” on the one it guessed. “The dashboard will be in this language, and your team's lead will talk to you in it.”

    Pick: your language, then Continue.

    Next: the program screen.

  2. Choose a program for your team

    You see: “Choose a program for your team”, with a card for Claude Code (“from Anthropic”) and one for Codex (“from OpenAI”). While harnsy looks, each says “Checking this computer…”; then “Installed” or “Not found on this computer”, and “Signed in” or “Sign-in needed”. Under the title: “Your team is a group of AI helpers that work together. You decide what they work on.”

    Pick: the program you installed. If it is not found, press Install Claude (or Install Codex): it opens the program’s own instructions. If sign-in is needed, press Sign in to Claude (or Sign in to Codex) and follow step 3. Then Check again. To use the other program, Use Codex instead / Choose another program.

    Next: when the card says “Claude is ready” (or “Codex is ready”), go on.

  3. Sign in (only if needed)

    Claude: “Sign in to Claude”, two steps: “Open Anthropic’s sign-in page” (“Sign in there with your Claude account.”), then “Paste the code from that page” (“After you sign in, the page shows a code — paste it here.”). If the code does not fit: “This code did not fit. Copy the whole code from the page and paste it again.”

    Codex: harnsy runs Codex’s own device-code sign-in for you: “Open OpenAI’s page” (“Any device will do.”), “Type this code there” (a code like WQT2-BZDCE), “The code is valid for up to 15 minutes.” If it does not finish: “Sign-in to Codex did not finish. Press “Sign in to Codex” again.”

    Where your login is kept: in the program’s own place on this computer. For Claude Code: harnsy does not read the login to use it and does not send it anywhere; it only asks Claude Code whether you are signed in. Before it changes Claude Code’s settings file, which can also hold your login, harnsy keeps a backup copy on this computer (see Keys, logins and connections). For Codex: harnsy looks in Codex’s own login file for a saved login (it reads only whether one is there, and does not copy, keep or send it), or checks whether OPENAI_API_KEY is set.

    Next: back to step 2; “… is ready”.

  4. Name your company

    You see: “You’re the CEO now.” “What should we call your company?” with “My First Company” filled in. “Your company will have teams, leads and AI employees. You set the direction. They handle the work.”

    Pick: keep the name or type your own, then Continue.

    Good to know: the first run says “company”; after it the dashboard says “Organization”. It is the same thing.

  5. Your first project, and what kind

    You see: “Every company starts with a project.” “Project name” with “My First Project” filled in. “Projects organize work. Each project has its own team, tasks and goals.” Under “What kind of project” two choices: New project (“Start from scratch. We create an empty folder for it.”) and My project (“Work in a folder you already have — a website, an app, your documents.”).

    Pick: New project → go to step 6. My project → go to step 5b.

  6. Show your folder

    You see: “Your project’s folder” (an example ~/code/my-project). When you type, “Checking the folder…”, then “Folder found: <folder>”.

    Pick: type the full path (starting with / or ~), then Look through my project.

    If it refuses: “There is no such folder on this computer. Check the path.” · “This folder is outside your home folder. harnsy works only with folders inside it.” · “This is your whole home folder. Type the path to your project’s folder inside it.” · “harnsy cannot use this folder: it is hidden, temporary, or holds harnsy's own data. Choose a project folder of your own.”

    Next: “Looking through your project”: “Your lead opens it to read only. Nothing in your folder is changed.” (The lead runs read only.) Then a card “Plan ready”. Until you accept, “Agents on this computer change nothing.” Press Accept the plan (or Stop). After that the lead starts work. Skip to step 8.

  7. What will your team work on?

    You see: “What will your team work on?” Four choices: Software development (“Making websites and computer programs.”), Marketing & content (“Writing texts and helping people learn about your work.”), Business operations (“Organizing everyday work, such as reports and lists.”), Something else (“Choose this if none of the other choices fits.”). Below: “What do you want to accomplish?” with an example “a website for my bakery with the menu and opening hours”. “We'll suggest the right AI employees for your project.”

    Pick: a kind of work, and write your goal in your own words.

  8. Meet your first team

    You see: “Meet your first team.” “Proposed team for “<project>”, from the harnsy catalog. Remove anyone or hire more.” The lead is marked “you talk to this one”. Each person has a card with skills.

    Pick: Remove <name> for anyone you do not want, + Hire more specialists to open the catalog, then Create my team (with a number: “Create my team (2)”). If the catalog does not answer, “The catalog did not answer, so this is the built-in team.” For the first run, there is a limit: “That is the most for the first run: hire the rest later in Roles.”

    Good to know: “Every change you accept is saved to git, so you can go back. You can turn it off in the project’s settings.”

  9. Putting your team together

    You see: “Putting your team together.” Three lines tick off: “Saving your company, project and team”, “Opening your lead’s window” (“Claude in a new terminal window”), “Your lead is reading its role” (“Usually 10–30 seconds”). “Your lead is starting in its own window. The chat opens as soon as it is in.” When done: “Company, project and team saved”, “Lead’s window opened”, “Your lead is in”.

    If it fails: “Your lead did not start. Your company, project and team are saved. Only starting the lead failed.” Press Open the lead’s window or Try again; see “If something goes wrong”.

    Next: the chat with your lead opens.

  10. Talk with your lead, and give the first task

    What happens: your lead greets you in your language, says in a line what it understood, proposes a first goal in one sentence and starts. It picks a first task small enough to finish within the hour and visible to you, and hires the smallest team for it from the catalog (usually one or two roles; the hire cards are in the chat and you press to hire, so nobody joins without you). Then it tells you: who is on it, which task, where to look (“Tasks”), and how work goes from here: write to the lead in the chat or comment on a card; the lead splits it into tasks for the team; if something is not right, say so and the lead redoes it.

    You see: the guide bar “First run · step n of 6”: Program and sign-in · Company and project · The lead hires the team · Talk with the lead · First task · Check the result. A goal card for you to confirm; the lead asks you one question at a time, with options, only when the work needs the answer.

    Pick: answer the lead’s questions; confirm the goal; press the hire cards.

    Next: the task board “Tasks”: each card is a piece of work. When the first task reaches Review, open it and press Accept (or Return… and say what to fix). Then ask the lead for the next thing. Show the whole dashboard ends the guide.

    ---

Organization and project

The first run says “company”; the dashboard afterwards says “Organization”. It is the same thing.

  • An organization is your company: the group that holds your projects.
  • A project is one folder with its own lead, team, tasks and goals.

Example. You run a small studio, “Acme Studio”. That is one organization. Two projects live in it: “Website” and “Mobile app”: two folders, two leads, two teams. You make a second organization only for a different client or business whose people, goals and roles should not mix.

To add more. On the Organizations page press “New organization” and “Add organization”, or “New project in <organization>”.

Limits. The free harnsy has one organization and two projects, with no limit on agents. harnsy Max sets more organizations and projects. If you hit the limit, a message says so and your organization keeps working.

Your second project

The guided first run appears only while the node has no company. For a new project later, press “New project in <organization>” on the Organizations page. Its lead has its own first meeting with you; there is no tour.

What the Claude Code and Codex paths do not share

  • Messages: harnsy delivers to Codex through its queue; a running Codex takes a message at the end of its turn. A person’s answer to an agent question also goes as one queued message.
  • Questions and permissions: Codex’s own questions can show on the dashboard (one choice per question, a typed answer allowed). Codex’s approval prompts do not reach the dashboard: they stay in its terminal window. For Claude Code both reach it.
  • Hooks: the installer adds its briefing hook to ~/.codex/hooks.json only if ~/.codex exists; Codex may ask you to trust the new hook the next time it starts. harnsy opens its Codex with folder trust given as command-line flags and its update check off.
  • Phone: harnsy’s phone access is its own dashboard access. (Nothing is said about other vendors’ remote features.)
  • The lead: the lead can run on Claude Code or Codex; you pick it on the first screen. A lead on Codex has had no real first-hour run that the product team can point to.
  • Chat with a live agent: documented as Claude so far in the product’s API notes.

If something goes wrong

  • “The lead did not open: Claude not found.” harnsy cannot find Claude Code. Install it and sign in. If it is installed, run harnsy install in a terminal where claude works (it saves that PATH), restart harnsy, and press “Try again”.
  • “The lead did not open: no terminal.” No terminal is chosen. Press “Choose a terminal”, or set terminal.driver: tmux in ~/.harnsy/config.yaml, restart, and press “Try again”.
  • Claude signed you out. The lead’s page asks you to sign in again (a link and a code). After that, harnsy sends the lead its first message itself.
  • “My project” refuses the folder. Type the full path starting with / or ~. The folder has to exist and be inside your home folder; hidden, temporary or harnsy’s own folders, and the home folder itself, are refused.
  • Two Claude Code installs, the older one first. Run claude --version (on Windows where.exe claude) and keep one.
  • Behind a company proxy nothing connects. Settings › Reach from outside › Proxy, and “Check”.
  • More: Troubleshooting.

Troubleshooting

Update

Upgrade

harnsy never checks for updates by itself. Check, then update:

Shell
harnsy update --check
harnsy update

The dashboard has the same as “Check for updates” and “Update” buttons. Running the install command again also works. Your data in ~/.harnsy stays. The node restarts for a few seconds, and agent sessions keep running.

Going back

After an update:

Shell
harnsy update --rollback --yes

Or install an older release over a newer one (the variable goes to sh, not to curl):

Shell
curl -fsSL https://harnsy.dev/install.sh | HARNSY_VERSION=<tag> sh -s -- --allow-older

Remove

Shell
harnsy uninstall --dry-run
harnsy uninstall

It removes the service, the tray, the program, and only the settings entries the install itself added (the briefing and answer hooks, the auto-mode entries, the status line; yours is put back if the install wrapped it), after showing a diff and asking.

More about the installer

What the installer does

Everything it writes, everything it asks, and what it leaves alone. harnsy install --dry-run prints every step, the diff of every file it would change and the path of every file it would create, and changes nothing.

It stays in your user account.

Everything goes into your own user directories. No sudo or admin rights. On Linux and macOS it doesn’t change PATH or your shell profile; if ~/.local/bin is not on PATH, it tells you, and you add it yourself or call harnsy by its full path. On Windows it adds %LOCALAPPDATA%\harnsy\bin to your user PATH (once, no administrator rights); windows opened before keep the old PATH, so type harnsy in a new one. If it cannot read or change your user PATH, it says so and tells you to add the folder by hand (Settings → Environment variables). harnsy uninstall takes that entry out again.

It checks the download.

The one-line installer downloads the release for your OS and CPU from GitHub over HTTPS and stops if the file is missing from the release’s SHA256SUMS or doesn’t match it. On Linux and macOS it unpacks into a temp folder, runs harnsy install from there and deletes the folder when it’s done. The check catches a broken or cut-off download; the sums come from the same release.

It sets up three things without asking.

The program, an install record and a background service for your user only. The service starts now and at every login.

Written without a question on a fresh install
LinuxmacOSWindows
The program (a copy)~/.local/bin/harnsy and the link ~/.local/bin/ccbusas on Linux%LOCALAPPDATA%\harnsy\bin\harnsy.exe
Install record~/.local/share/harnsy/install.json and hooks/harnsy-introduce.pyas on Linux%LOCALAPPDATA%\harnsy\install.json
A service: starts now and at login, restarts after a crashsystemd user unit ~/.config/systemd/user/harnsy.serviceLaunchAgent ~/Library/LaunchAgents/com.github.butschster.harnsy.plist, log in ~/Library/Logs/harnsy/Task Scheduler task harnsy, least privilege; if Windows refuses it, the value harnsy under HKCU\Software\Microsoft\Windows\CurrentVersion\Run (no restart after a crash)

If a different service file or task is already there, it shows it and replaces it only after your yes. An existing ~/.local/bin/ccbus file is moved to ccbus.pre-harnsy.

When you run it yourself, it asks before everything else.

Each of these is a [y/N] question. Only y or yes counts; no answer, no terminal or --dry-run means no. Since 0.8.0, no terminal means no only if you did not say yes up front (see “Say yes up front”); --dry-run is always no.

  • Whether a terminal runs your agents, while nothing is chosen yet (tmux if it is installed, otherwise harnsy’s own terminal host; on Windows its own terminal host), saved as terminal.driver in harnsy’s config.yaml.
  • The tray icon (Linux and Windows): on Linux, ~/.local/bin/harnsy-tray. Starting it at login is a second question.
  • A startup hook for new sessions in ~/.claude/settings.json and ~/.codex/hooks.json, only if ~/.claude or ~/.codex exists (not on Windows).
  • A status line in ~/.claude/settings.json, only if you have none.

For each settings file it first shows you the exact change. A file that already exists is first copied to ~/.local/share/harnsy/backups/ (Windows: %LOCALAPPDATA%\harnsy\backups\). --accept and --yes answer yes for you, only when you give them (0.8.0 and later). --no-tray, --no-hooks and --no-statusline skip a step.

It stays on your machine.

The dashboard on 127.0.0.1:7788 and the agent port on 127.0.0.1:7790 listen only on this computer. The service is also given 127.0.0.1:7789 for other nodes; that port opens only after you issue a node token, and never without a harnsy Max key. harnsy has no telemetry and never checks for updates. By default it talks only to your harnesses on this machine and to nodes you connect; the services it can reach once you add a key or turn a feature on are listed in the FAQ “Where does my data go?”. While a key is installed, harnsy checks it with the license service (lic.harnsy.dev) about once a day, sending the full key, a hash of the machine’s ID (the ID itself never leaves the machine), a random one-time value, the machine’s name in the license panel, the OS and architecture, the harnsy version and its build date.

It doesn’t touch:

  • MCP servers: it prints the optional claude mcp add line for you to run
  • ~/.claude.json
  • Codex’s ~/.codex/config.toml
  • OpenCode’s settings

Later, while it runs: only with claude.auto_trust: true in config.yaml (off by default) harnsy marks a project folder trusted in ~/.claude.json before it opens Claude Code there, after copying the file to claude.json.bak in ~/.harnsy. Codex opened by harnsy gets folder trust as command-line flags; no file is written.

A particular release, or back to an older one

A particular release, or back to an older one: curl -fsSL https://harnsy.dev/install.sh | HARNSY_VERSION=<tag> sh (the variable goes after the pipe). The database only gains tables and columns, so an older build still opens it.

harnsy version shows the build you have.

Behind a corporate proxy

Behind a corporate proxy (since 0.9.1): set HTTPS_PROXY (and HTTP_PROXY) to the proxy and NO_PROXY to the hosts that go direct, and keep localhost,127.0.0.1,::1 in it. harnsy reads them once, when it starts: on Windows set them as user variables, then sign out and in again; on Linux and macOS add them to the harnsy service (systemd unit or launchd plist), then restart it. harnsy net check then tells you, host by host, whether it can be reached or why not (proxy login, TLS inspection, no route).

Open agents from harnsy

~/.harnsy/config.yaml

terminal: driver: tmux # or: conpty

Set by hand in ~/.harnsy/config.yaml; the installer or --first-run sets it for you.

Questions about installing

Before you start

What do I need first? A computer with Linux, macOS 13 or newer, or Windows 10 (1809) or newer; and Claude Code or Codex, installed and signed in, on a plan or API key from Anthropic or OpenAI that works with it. The steps above walk you through the account, the install and the sign-in. harnsy does not install Claude Code or Codex for you.

Which plan do I need? Which plans include Claude Code or Codex is the provider’s rule, and it changes. Read Anthropic’s and OpenAI’s own pricing pages, linked in Step 1. harnsy asks the program only whether you are signed in.

Do I need a special terminal? No. harnsy runs your agents in a terminal it drives, and picks one for your system: on Linux and macOS tmux if it is installed (3.1 or newer), otherwise harnsy’s own terminal host; on Windows always harnsy’s own terminal host. You install nothing for this, and the dashboard shows each agent live. Without one, messages, teams and the dashboard still work; harnsy just cannot open or reopen agents.

Do I need to know how to code? No: you describe goals in plain words and the team plans and does the work. To start you install your AI program and harnsy (a command or two in a terminal) and sign in, and the steps above show how. Judging technical results, such as code, is easier with someone technical at hand.

Install

What should I know before I run a command that downloads a script? You can read the script first: open the address in your browser. --dry-run prints every step and every change and writes nothing. The installer works in your user account and does not ask for administrator rights, and it checks the download against the release’s SHA256SUMS (that shows the file arrived intact, not who made it). Every change to your own settings files is shown as a diff first, and a backup is kept.

What does the installer change on my computer? It puts the program in your user folder and starts it as a background service for your account. With --first-run it also says yes in advance to harnsy’s own set (agents open in their own windows, each new agent gets a short note about harnsy, you can answer agents’ questions from the browser, agents talk to harnsy without asking each time); that changes the settings files of Claude Code and Codex (hooks). It sets up no tray icon and no status line. At the end it prints “What changed on this computer” and how to undo it. The full list is “What the installer does” below. To undo the install, run harnsy uninstall: it removes the program, the service and the tray that harnsy installed, and, after showing you each change and asking, the entries harnsy added to your Claude Code settings (its hooks, the permission entries for auto mode and the status line if it set one up); a backup is made first, and the backups, your data in ~/.harnsy and anything you added to those settings later stay. Run without a terminal, it asks nothing and leaves those settings entries in place.

Windows says harnsy.exe is a threat. What do I do? Windows Security sometimes flags harnsy.exe; we believe this is a false positive. Check the download first, then exclude only harnsy’s folder: the steps are in Troubleshooting.

“harnsy: command not found” after install. On Linux and macOS the installer does not change PATH or your shell profile; if ~/.local/bin is not on PATH it tells you, and you add it yourself. On Windows it adds %LOCALAPPDATA%\harnsy\bin to your user PATH (no administrator rights, once); windows opened before keep the old PATH, so type harnsy in a new one. If it cannot read or change your user PATH, it says so and tells you to add the folder by hand (Settings → Environment variables). harnsy uninstall takes that entry out again.

Can I install without a terminal? harnsy installs with a command, so you need a terminal for that one step. You can ask your AI program to do it for you (the prompt on top of this page); it tells you what the install changes and waits for your yes. If your AI program may not run the installer, it asks you to run the command yourself.

First team

Why does the first run say “company” and the dashboard “Organization”? They are the same thing: your company is the group that holds your projects. The first run uses the simpler word.

Does the lead always study my project first? Only when you start from a folder you already have (“My project”): it reads the folder without changing anything, shows a plan, and waits for you to accept it. For a new project it asks a few questions, proposes a first goal and gets to work.

Can I use Codex instead of Claude Code? Yes: Codex is the other choice on the first screen, and the lead can run on either. Codex’s questions reach the dashboard, but its approval prompts stay in its own terminal window.

Does harnsy see my Claude login? harnsy does not read it to use it and does not send it anywhere; it asks Claude Code whether you are signed in. A backup of Claude Code’s settings file, which can hold the login, stays on this computer: see Keys, logins and connections. For Codex it looks only whether a saved login is there; it does not copy, keep or send it.

Why can I not add a third project? The free harnsy has one organization and two projects, with no limit on agents; harnsy Max sets more. If you hit the limit, a message says so and your organization keeps working. (Since 0.11.0.)

Where do I ask something that is not here? Ask a question.

---