Skip to content

setup.md

Latest commit

 

History

History
65 lines (57 loc) · 3.93 KB

setup.md

File metadata and controls

65 lines (57 loc) · 3.93 KB
Raw

Set up Isbell on this Mac

For the agent doing the setup. Isbell lets its user reach the agents on their Macs from a browser: isbell runs a gateway on each Mac, beside herdr, where the agents run.

Rules

  • Never print, read or repeat the space key. Never put it in a command line. space init and space show print it, so send their output to /dev/null.
  • Ask the user before installing herdr.

Checklist

  • uname -sm is Darwin arm64. Otherwise stop: the installer is for Macs with Apple silicon; the README says how to build from source.

  • Install or upgrade: curl -fsSL https://isbell.fmap.dev/install.sh | sh. Make sure ~/.local/bin is on the user's PATH.

  • herdr is installed: command -v herdr in a login shell. If not, with the user's yes: curl -fsSL https://herdr.dev/install.sh | sh.

  • The space: if isbell space show >/dev/null 2>&1 succeeds, there is one already. If not, ask the user whether this is their first Mac:

    • first Mac: isbell space init >/dev/null;
    • another Mac: the user runs isbell space join <key> themselves.

  • Gateway service, from the user's login shell, so it finds herdr and the agents: $SHELL -lc 'isbell gateway install'.

  • Optional, if the user runs Claude Code, Codex or pi: with their yes, the hook that lets the board show what each agent is asked and doing, and records each session in ~/.isbell/sessions so a project's Sessions can resume it after its pane is closed. A machine with an older hook gets this by installing again. Fetch it once: curl -fsSL https://isbell.fmap.dev/agent-hook.sh -o /tmp/agent-hook.sh, then for each agent the user runs:

    • Claude Code: sh /tmp/agent-hook.sh install claude. It registers itself in $CLAUDE_CONFIG_DIR/settings.json, else ~/.claude/settings.json; for another config directory (a wrapper such as reclaude keeps its own), add --config-dir DIR. Sessions already running take it once restarted. Claude Code deletes a session's transcript after cleanupPeriodDays (30 by default), and a deleted one cannot be resumed: ask the user whether to raise it in that settings.json.
    • Codex: sh /tmp/agent-hook.sh install codex, into $CODEX_HOME/hooks.json, else ~/.codex/hooks.json. Tell the user that Codex asks to trust the new hooks when it next starts (choose Trust all), and that they report only from Codex started with --no-daemon: Isbell starts it so. A session's chat is read from the agent's own record, so for Codex started by hand in herdr suggest alias codex='codex --no-daemon' in ~/.zshrc. Without it, the chat finds the record by the pane's directory and when its Codex started, as long as no other Codex works in that directory.
    • pi: sh /tmp/agent-hook.sh install pi. It writes an extension to $PI_CODING_AGENT_DIR/extensions/, else ~/.pi/agent/extensions/, which pi loads when it starts: sessions already running take it once restarted. For pi's status on the board, herdr needs its own integration too: herdr integration install pi.

  • Check:

    • isbell gateway status says running;
    • isbell machine list shows this Mac online.

    If either check fails, look at the end of ~/Library/Logs/isbell/gateway.log.

  • Tell the user:

    1. Run isbell space show in your own terminal and copy the key.
    2. Open https://isbell.fmap.dev and paste it.
    3. Start agents inside herdr (run herdr); Isbell sees what runs there.
    4. For another Mac, give its agent this same file.

Uninstall

isbell gateway uninstall, isbell space leave, then delete ~/.local/bin/isbell. With the agent hook installed, first sh ~/.isbell/hooks/agent-hook.sh uninstall claude (with the same --config-dir), … uninstall codex and … uninstall pi for each agent it was installed for, then delete ~/.isbell/hooks, and ~/.isbell/sessions unless the user keeps the sessions' records.