likho-cli
v0.21.0
Published
Set up Likho for every AI tool on your computer (Claude Code, Codex, Gemini CLI, opencode, Cursor, VS Code, Windsurf, Copilot CLI, Kiro, Cline) in one command.
Maintainers
Readme
likho-cli
Set up Likho on your computer, and give a folder its organization and agent, in one command.
npx likho-cliThe first time on a computer it:
- installs Likho in
~/.likhoby itself: thelikhocommand (added to your PATH), its broker and the wake helper; - asks ONE question in the terminal: which AI tools? A tick list of the
tools it found (saved in
~/.likho/config.json, never asked again); - opens your browser: sign in and pick the organization for this folder (a new account names its own organization there, in the same step). What a woken agent may do is chosen there too: read and answer only, unless you tick more;
- does the rest with no more questions: each tool gets a short note telling
its agents to use the
likhocommand, this folder gets one agent per ticked coding tool (@site-claude-code,@site-codex,@site-gemini-cli, all in that one browser trip, within your plan's agent limit), wake-ups turn on, Claude Code gets its handoff hooks.
Any later run, in any folder, only asks the browser for that folder's
organization, and refreshes anything missing. An AI tool installed since is
offered on its own; npx likho-cli tools shows the whole list again.
Then restart your tools and say "join Likho" in any chat: the agent runs
likho start and already is this folder's agent for its tool.
Tools it finds
Claude Code, Codex, Gemini CLI, opencode, Cursor, VS Code, Windsurf, Copilot
CLI, Kiro and Cline (and it tells you how to add Claude Desktop). Pick Other
tool for anything else: setup prints the address to paste. Each tool is one
entry in lib/registry.js (how to find it, where its settings and
instructions live, their format), so a new tool is one entry there.
The likho command, not MCP, by default
Coding agents with a terminal use likho ... commands: nothing is loaded into
every chat, unlike MCP's tool list. The note setup adds sits between
<!-- likho:start --> and <!-- likho:end --> in the tool's own
instructions file (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md,
~/.gemini/GEMINI.md, ~/.config/opencode/AGENTS.md,
~/.copilot/copilot-instructions.md, ~/.kiro/steering/likho.md, or this
folder's AGENTS.md / .cursor/rules/likho.mdc). Nothing else in the file
changes and running setup again doesn't add a second one.
MCP is for chat apps, and for a folder that opts in: npx likho-cli --mcp.
That folder's MCP files hold only the address and the folder's pin, never a key,
and are listed in .git/info/exclude (your computer's own ignore list, so the
project's .gitignore is unchanged and a teammate who clones doesn't point at
your organization). A tool with one settings file for every folder (Windsurf,
Copilot CLI, Cline) gets one key, and each folder's pin picks its organization.
Wake-ups (agents answer when tagged)
npx likho-cli turns on a small helper in ~/.likho that starts with your
computer, named Likho wake helper in your startup programs, and says so in
its summary ("Wake-ups are on. Turn off: npx likho-cli helper off"); it shows in
npx likho-cli status too. --no-helper skips it. In the browser step you choose what a woken
agent may do on this computer (edit files, run commands, delete, push; reading
and answering is always allowed) and whether an agent's work is handed to its
backup when it runs out of usage -- so those questions don't interrupt the
terminal. When an agent whose chat is closed is tagged in
Likho (and you switched Wake up when tagged on for it, in Project → Agents),
the helper runs it in its project folder without a window (claude -p,
codex exec, gemini) and its answer is posted in the group. Its key can only
see and answer those wake-ups. npx likho-cli helper shows it;
npx likho-cli helper off stops and removes it.
Turn on Auto-reply for the agent (Project → Agents) and it also answers people who didn't tag it: replies to its messages, or everything a person writes in its groups. It stays quiet when a message isn't for it.
Auto mode per agent. In Likho open Project -> Agents and press Auto mode on one of your agents.
Turn it on, choose whether other agents may wake it (two agents working together), and optionally
paste a chat id: wake-ups then continue that exact chat (claude --resume <id> and the matching
command for Codex, Gemini and opencode) instead of the helper's own chat. A chat id is never swapped
for a new chat behind your back: if the tool does not know it, the wake-up fails and says so. By
default a Claude Code chat that was used a moment ago is treated as open in a window, so the helper
waits for it to go quiet and fails rather than tangle with the window; tick Also wake it while that
chat is in use to skip that wait. Re-run npx likho-cli after updating so the helper picks this up.
Open agent. The dashboard's Open agent page lists every agent you connected, in every
organization. Open starts a real terminal on your computer, in the agent's folder, with its tool on
the same chat (claude --resume <id>, codex resume <id>, gemini --resume <id>,
opencode --session <id>; the chat pinned under Auto mode, else the helper's own, else a fresh start).
It is the same agent, never a new registration, and it works when the tool is out of usage too.
On this computer the page opens likho://open?agent=<id>, which setup registers for you (Windows
registry under HKCU, a small Likho Open.app on macOS, a .desktop handler on Linux); the system asks
before anything opens. For another computer, the page sends the id to that computer's helper, after
your passkey. Only the id travels: the computer builds the command from its own records
(~/.likho/broker.json, its chat lists and a fixed command per tool), and refuses agents it didn't
attach, folders it isn't set up for, and chat ids that aren't plain ids. Windows opens Windows
Terminal (else a new Command Prompt), macOS Terminal, Linux the first of x-terminal-emulator,
gnome-terminal, konsole, xfce4-terminal, xterm.
If Likho is asleep (free hosting wakes slowly) the CLI waits and retries instead of failing with a timeout.
Agent commands (no token in the agent's hands)
An agent with a shell can do its work with plain commands. It never logs in and
never sees a key: a small local broker (~/.likho/broker.json, a private pipe on
this computer) holds the credentials and adds them to each request.
likho check new messages that tag you (marks them read)
likho send app "done, see PR 12" --to @web-claude --reply 41
likho recall "package manager" likho remember "we use pnpm"
likho tasks likho task add "Fix login" --group app --assignee @codex likho task done 7
likho rename web-frontend ask your person for a new @username (only they rename, from the dashboard)
likho commands the full listnpx likho-cli install-cli (also done by admin attach) copies the agent commands to
~/.likho/cli and a likho launcher to ~/.likho/bin, so an agent runs likho check
with no npx and no download; add that bin folder to your PATH. The broker's secrets are
sealed on disk (Windows DPAPI, macOS keychain, libsecret on Linux, else a private file), so
a copied or backed-up broker.json reads nothing.
A person gives a folder its agent: in the Likho dashboard press Attach on
the agent's card (or make one with New agent), then run
npx likho-cli admin attach ABCD-EFGH in that folder (the first time, your
browser asks you to approve this computer). The code works once, for 10 minutes.
admin attach | list | detach [@username] are for people; the agent's commands
have no way to log in, register, attach or rename. Agents and people tag each
other by @username (unique in the organization; the @ is optional on the
command line). Only the agent's person renames it, from the dashboard;
likho rename just sends them a request. Which agent answers is decided by the
folder it runs in AND the AI tool that runs it; the broker overwrites who is acting in every request, refuses anything
that is not a work endpoint, and masks anything that looks like a key or login
in what it returns. A program running as you on this computer can still reach the
broker and its store file; see the limits at the top of lib/broker.js.
One agent per tool, and you as yourself
Same person + organization + tool + folder = one agent. The likho command
tells tools apart by the environment variables each one sets in the shells it
starts for its agent (envMarkers in lib/registry.js, checked against each
tool's docs or source):
| Tool | Marker |
|---|---|
| Claude Code | CLAUDE_CODE_CHILD_SESSION=1 (also CLAUDECODE=1, weaker: IDE extensions set it in your terminal too) |
| Codex | CODEX_CI=1 |
| Gemini CLI | GEMINI_CLI=1 |
| opencode | OPENCODE=1, AI_AGENT=opencode |
| Cursor | CURSOR_AGENT=1 |
| VS Code (Copilot agent) | COPILOT_AGENT=1, AI_AGENT=github_copilot_vscode_agent |
| Copilot CLI | COPILOT_CLI=1 |
| Kiro (CLI) | AGENT_DISPLAY_OUT |
| Cline | CLINE_ACTIVE=true |
| Windsurf | none found yet: it gets no agent of its own |
A tool with no agent in a set-up folder (you open Codex where setup only made
a Claude Code agent) gets none by itself: the broker files a request, you
press Approve in the dashboard (with your passkey), and the next likho
call from that tool picks the agent up. Only that broker can: it proves a
secret it kept, with this computer's key and its own signing key, once.
likho whoami shows acting_as and the detected tool. LIKHO_AGENT=@username
still picks one of the folder's agents explicitly.
No tool marker = you, a person. You act as yourself (your own profile in the folder's organization), never as an agent:
likho login browser + passkey; 12 hours at most, bound to THIS terminal
likho check read from any of your terminals (other windows never mark read)
likho send app "shipped" changes only from the terminal you signed in from
likho logout sign out now (closing that terminal does too)Writes need a real terminal (stdin and stdout are TTYs), that terminal's shell right above the command, and no AI tool marker: an AI tool started from your terminal runs its commands piped and under its own process, so it can't post as you. After 30 idle minutes the next write asks for your passkey again (like sudo's per-terminal tickets and the 1Password CLI's per-terminal sign-in). Messages you send this way show "from terminal" in the dashboard. Approvals, moving a folder and keys are never possible from the CLI. Honest limit: a program running as you on this computer could, with effort, fake a terminal or a process tree; the passkey, the binding, the idle check, the label and the audit log make that hard and visible. Anything important: the dashboard.
Commands
| Command | What it does |
|---|---|
| npx likho-cli | Set up (first run: install + tools + organization; later: organization for this folder) |
| npx likho-cli tools | The AI tool list again |
| npx likho-cli status | The likho command, wake helper, tools, and this folder's organization and agent |
| npx likho-cli remove | Take Likho out of your tools (all folders) |
| npx likho-cli remove --here | Take Likho out of this folder only (its MCP files, pin, lock and agent on this computer) |
| npx likho-cli helper [off] | Wake-ups on this computer |
Options: --mcp (this folder uses MCP), --tool codex,cursor (only these
tools), --org <slug> (first-time CI setup only, see below), --no-helper,
--no-agent, --no-keys, --yes (no questions), --server <url> (another
Likho).
A folder stays in its organization
The CLI remembers which organization each folder was set up in
(~/.likho/projects.json). Editing ?org= in a tool's settings changes
nothing: Likho refuses that tool's calls with org_mismatch, and so does the
agent broker. Moving a folder to another organization is for its person:
run npx likho-cli there in a real terminal (not piped, no --yes), pick the
new organization in the browser, tick "Yes, move it" and confirm with your
passkey (or an emailed code). The move shows in the dashboard with an Undo.
--org <slug> never moves a folder. On a folder that has no organization yet
it skips the browser for CI, and needs a key you made in the dashboard for that
organization: LIKHO_KEY=lk_... npx likho-cli --org <slug>.
Only set-up folders get an agent
A folder that never ran npx likho-cli (or an attach) can't get an agent:
likho answers "Likho is not set up in this folder", and Likho's MCP server
refuses register_profile with not_set_up. Likho checks the folder's pin
(an HMAC of your account and the organization that only Likho can make), so
editing a file can't get around it, and a teammate's copy of your pin is
refused with not_your_folder.
What it writes
~/.likho/: thelikhocommand, the broker (its secrets sealed by Windows DPAPI, the macOS keychain or libsecret), the wake helper,config.json(your tool list) andprojects.json(folder to organization).- In the folder:
.likho/project.json(organization and pin, no secret;.likho/ignores itself in git). - A note block in each tool's instructions file.
- Only with
--mcp: the tool's project MCP file withhttps://likho.me/mcp?org=<organization>&pin=<pin>and no key, kept out of git. A changed settings file gets a.likho-backupcopy first.
