hilos-agent

Run your own coding agent — Claude Code, Codex, Cursor, opencode, Hermes, or any command — as an autonomous teammate inside a hilos channel.

It connects to hilos over MCP, watches for @mentions of your agent in a git-linked channel (including thread replies), runs your coding agent in a local checkout, and — by default — opens a PR for review. Your code and your git/gh credentials never leave your machine — hilos only relays messages.

hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
  human: "@scout fix the navbar overflow"
  agent: branches, runs your coding CLI, commits + pushes, opens a PR
  agent: posts a report card with the PR link
  human: Approve  ▶  hilos merges the PR
         Reject   ▶  hilos closes the PR
         Changes  ▶  agent re-works with your note

Prefer approve-before-push? Set "gate": true — the agent then posts the proposed diff as a card and pushes only after you Approve (nothing leaves your machine until then).

Quick start

In hilos: open your agent's profile → Connect → copy the hilos-agent --join … command. Then on your machine, run it from inside your repo's folder — the daemon matches the repo by its git remote, so no config is needed:

cd ~/code/your-repo
npx hilos-agent --join <blob>        # token + endpoint from the link; repo auto-detected from cwd

Running from elsewhere, or want to map several repos explicitly? Use a config:

// ~/.hilos/agent.json  (or ./hilos-agent.json)
{
  "url": "https://hilos.sh/api/mcp",
  "token": "mgo_…",
  "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "opencode run", "agy -p", any command
  "codingModel": "",  // model preset tier ("opus" | "sonnet" | "haiku") resolved at run time against the CLI's own model list (Cursor only today); "" = the tool's default
  "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
  "defaultBranch": "main",
  "gate": false,               // default: open a PR directly. true = approve-before-push
  "heartbeatMs": 180000,       // long runs post one "still working…" thread reply this often (0 = off, min 15s)
  "chatTimeoutMs": 90000       // cap a chat reply / plan-ack so a stalled model can't go silent
}

Staying responsive. Every code task posts an instant acknowledgement (under a second), and — if your server exposes edit_message and a chatCmd is set — a quick plan ("On it — I'll do X, then open a PR") edits into it. On a run longer than heartbeatMs (default 3 min; env HILOS_HEARTBEAT_MS, 0 disables, clamped to ≥15s) the agent posts one progress reply in the thread then edits it in place with elapsed time + the CLI's latest line — so the channel shows it's alive without thread spam. When the run ends, that message is retired to a short "done" line. A run that times out or errors says so honestly (with a stderr tail) instead of claiming "no changes". Chat replies use the faster chatCmd (when unset, derived from codingCmd's tool — a Claude daemon chats with Haiku, a Codex daemon with codex exec, and so on) bounded by chatTimeoutMs. The responsive surface needs a hilos server new enough to expose edit_message; older servers just skip the live edits.

hilos-agent          # watch every channel the agent is in
hilos-agent --channel <id>   # scope to one channel

How it works

• Trigger — an @mention of your agent in a channel that's linked to a repo.
• Chat or code? — the agent reads the conversation and decides with the model (via chatCmd), not a keyword list: a question/greeting/"let's just discuss" → a chat reply; anything asking for a change — including "just code it", "finish it", "approved", or "go for it" after a request, in any language → a code run.
• Repo resolution — the channel's linked repo is mapped to a local path via repos. No mapping → the agent says so and stops.
• Run — it branches off defaultBranch (refuses a dirty tree), runs codingCmd with the task, and stages the result.
• Continue the thread's PR — when the mention lands in a thread hilos says is about a pull request, the daemon works on that PR instead of opening a second one: it fetches the PR's head branch, commits there, and the same PR updates. It confirms with gh that the PR is still open first — a merged, closed, or fork PR gets a fresh branch, and the run says so.
• Merge / close on request — "merge it" from a workspace owner or admin in a PR thread is executed, not described. The daemon relays the request to hilos with the id of the message that asked; hilos verifies the person's role and that their message really asks for it, then acts with the workspace's GitHub App. The daemon never merges on its own judgment and holds no merge rights.
• Open a PR (default) — it commits, pushes with your git/gh, opens a PR, and posts a report card with the link. Review on the card: Approve merges, Reject closes, Request changes re-works.
• Recover an over-eager coding CLI — if the child commits or switches branches despite the edit-only prompt, the daemon pushes that HEAD under the task branch it owns. It never asks GitHub to open the default branch against itself, and a rejected PR creation includes GitHub's actual error in the report.
• Approve-before-push (gate:true) — instead, it posts the staged diff as a card and polls for your decision; Approve pushes + opens the PR, Reject discards the branch, Request changes re-runs with your note (bounded rounds).

Local folders (no repo required)

A channel doesn't need a linked GitHub repo to get coding work done. Map a channel to a plain local folder and the agent works in it directly — it edits the files in place (no branch, no commit, no PR), then posts a report of what changed. It's your own machine, so this is the same trust as running the CLI yourself.

// hilos-agent.json
{
  "folders": { "<channelId>": "/Users/you/notes-site" }
}

• Trigger — an @mention in a channel with no linked repo but a folders mapping. The same LLM router decides chat vs. code; a coding ask runs in the folder.
• Git folders — if the folder is a git repo, the agent snapshots git status before/after and reports the exact files it created/changed/removed plus a git diff --stat. It never touches your index, branches, pushes, or runs gh. On the report card: Approve keeps the changes (they're already live), Request changes re-runs in place with your note (bounded by maxRounds), Reject reverts only what this run changed (git checkout the files it modified, delete the files it created) — your pre-existing local edits are left untouched.
• Non-git folders — it still runs, but says up front it can't show a file-level diff or auto-undo; a reject asks you to revert by hand.
• A linked repo always wins — the folder map is only consulted when the channel has no repo link.
• Folder link registration — on startup the daemon registers each folders mapping with hilos (over the link_folder MCP tool) so the channel shows a folder chip — the folder's name, its full path, and which machine it lives on — without any manual step. It's best-effort and capability-gated: older servers that don't expose link_folder are skipped silently, and a failed registration only logs a line, never blocking the daemon. Registration happens once at startup, so a folders entry added while the daemon is running needs a restart to appear.

Deploy the folder with your own hosting CLI

Add an optional per-channel deploy target next to folders:

{
  "folders": { "<channelId>": "/Users/you/notes-site" },
  "deploy": { "<channelId>": { "provider": "vercel", "prod": false } }
}

prod:false means a preview deployment; prod:true means production. If the setting is absent, the daemon detects .vercel/ / vercel.json or .netlify/ / netlify.toml; with no marker, deploy stays off. Install and sign in to the matching CLI yourself (vercel login or netlify login). hilos stores no host credential and never deploys silently: ask explicitly to put the folder live, or use the report card's clearly labeled deploy action. The live URL comes back on the same report card. CLI output is secret-redacted, the child receives no HILOS_* variables, and failures remain caveats rather than false successes.

Embedding the daemon

run(cfg, opts) is the poll loop, and it's embeddable. Beyond handler/log it accepts:

import { run } from "hilos-agent/src/run.mjs";

const controller = new AbortController();
await run(cfg, {
  signal: controller.signal,   // abort → interrupts the poll sleep, cancels the
                               //         active job, and returns cleanly
  onEvent: (e) => {            // lifecycle events for a host UI (wrapped in
    // e.type: "status" | "task-start" | "task-done" | "task-error"
    console.log(e);            //   try/catch — a bad listener can't crash the loop)
  },
});
// later: controller.abort();  // run() resolves once the active job tears down

Event shapes: { type: "status", text }, { type: "task-start", channelId, messageId, text }, { type: "task-done", channelId, status }, and { type: "task-error", channelId, error }. Both options are optional and fully backward compatible — omit them and the CLI behaves exactly as before.

Model & permissions

You don't have to hand-write codingCmd: the agent's Connect via MCP panel in hilos has Model (Vendor default / Opus / Sonnet / Haiku) and Permissions (Ask before edits / Auto-approve edits / Skip all prompts) pickers that bake your choice into the generated --coding-cmd. Change it later by editing codingCmd in hilos-agent.json — the daemon re-reads the file between polls and applies it without a restart (your url/token are never affected). The next section explains what each permission level means.

Permissions / autonomy

codingCmd decides how much the coding agent can do on its own. Three levels, safest first:

• opencode run (runtime-gated). When the connected hilos server advertises runtime permissions, the daemon runs OpenCode through an authenticated loopback server and becomes its sole permission responder. A tool ask pauses mechanically, posts a card in the run thread, and resumes only after a channel member chooses Allow once, an exact harness-suggested Always rule, or Deny. Missing transport, expiry, and cancellation all reject the tool call. opencode run --auto deliberately bypasses these cards and keeps OpenCode's dangerous auto-approve behavior.

• --permission-mode acceptEdits (default). The agent edits files without prompting, but in headless claude -p a step that needs bash — run the tests, install a dep — has no interactive prompt to grant, so the task can stall. Good when the work is edit-only; frustrating for anything that needs to run commands.

• --dangerously-skip-permissions (recommended for independent agents). Full autonomy: the agent can run the tests, install deps, and finish hands-off. Caution: it can run any command in the repo you point it at — only use it on a repo and machine where that's acceptable. This is the option to pick if you want the agent to actually work on its own.

  "codingCmd": "claude -p --dangerously-skip-permissions"

• Approve-before-push (gate:true), most cautious. Independent of the two above — the agent still runs locally, but posts the proposed diff as a card and pushes only after you Approve. Pair it with either permission mode.

The default stays acceptEdits. Reach for --dangerously-skip-permissions when you want a truly hands-off teammate, and keep gate:true if you'd rather review before anything is pushed. OpenCode is the first harness with the runtime-card bridge; Claude Code, Codex, Cursor, and other adapters still follow their own CLI permission modes until their native approval hooks join the same vendor-neutral hilos substrate.

Hooks — stream a raw Claude Code session

Don't want to run a persistent daemon? You can still make your Claude Code CLI sessions visible to your team in real time. Claude Code hooks (shipped in 0448) let every tool call your session makes stream directly into your agent's live status card in hilos — no daemon, no extra process.

# Inside the repo you want to stream:
npx hilos-agent hooks install

# Or stream all your Claude Code sessions, everywhere:
npx hilos-agent hooks install --global

This writes PostToolUse, Stop, and SessionEnd hook entries into .claude/settings.json (project) or ~/.claude/settings.json (global), preserving any hooks you already have. Preview the block without writing anything:

npx hilos-agent hooks print

Requirements:

• npm i -g hilos-agent so the hilos-agent hook command resolves at hook time.
• A ~/.hilos/agent.json with url, token, and channelId. Generate these in the agent's Connect via MCP panel in hilos (same panel as --join).

What you get:

• Team members see "Editing lib/x.ts" or "Running pnpm test" on the agent's live card as each tool fires — without you doing anything beyond the install.
• Steps are coalesced into ~2s batches to keep traffic light.
• When a turn ends (Stop), the card settles to done. The next turn revives the same card — one card per session, not one per turn.
• Up to 20 unique files touched are surfaced so reviewers can glance at the scope before the report card arrives.

Privacy: project-level by default (only repos you opt into stream). Global kill switch: HILOS_HOOKS=off. The hook always exits 0 — it will never interrupt or break your CLI session.

Security

The daemon runs a coding agent that can execute code in your repo — exactly as if you ran it in your terminal — and uses your local git/gh to push. By default it opens a PR (nothing is force-merged; you review the PR, and merge/close run via hilos's GitHub App only for workspace owners/admins). Want a human checkpoint before anything is pushed? Set "gate": true. Keep your token in the config file or HILOS_TOKEN, never in shared shell history.

Flags

--join <blob> · --channel <id> · --config <path> · --coding-cmd <cmd> · --chat-cmd <cmd> · --once · --backfill · --no-gate · --help

Env: HILOS_TOKEN, HILOS_URL, HILOS_CHANNEL, CODING_CMD, HILOS_ONCE=1, HILOS_BACKFILL=1.