arcane-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,528 @@
+# Arcane Agents
+
+Built and maintained by [Thomas Rice](https://www.thomasrice.com), Co-founder of
+[Minotaur Capital](https://www.minotaurcapital.com).
+
+Arcane Agents is a local-first visual control room for terminal-backed AI agents.
+Each agent appears as a character on a 2D map, and selecting one opens its live terminal in the right panel.
+Common setups use Claude Code or OpenCode runtimes, but any terminal-accessible runtime can work.
+
+## What It Does
+
+- Manages agents as tmux windows.
+- Streams live terminal output into the browser via `node-pty` + WebSockets.
+- Tracks agent status (`idle`, `working`, `attention`, `error`) from pane output.
+- Lets you spawn agents from shortcuts or direct project+runtime combinations.
+- Stores state locally in SQLite.
+
+## Platform Support
+
+- Linux: fully supported and recommended.
+- macOS: core app works, but opening an agent in an external terminal (`↗`) is currently Linux-oriented (`xdg-terminal-exec`).
+- Windows: use WSL2 (Ubuntu or similar) and run Arcane Agents inside WSL.
+
+## Requirements
+
+- Node.js 20+ and npm
+- tmux (hard dependency)
+- At least one configured runtime command (for example `opencode`, `claude`, or `bash`)
+- Optional but useful:
+  - `git` (for worktree/discovery workflows)
+  - `xdg-terminal-exec` (Linux external terminal button)
+
+## Install (Non-Developers)
+
+1) Install system dependencies.
+
+Linux (Debian/Ubuntu):
+
+```bash
+sudo apt update
+sudo apt install -y tmux git
+```
+
+macOS (Homebrew):
+
+```bash
+brew install tmux git
+```
+
+Windows:
+
+- Install WSL2 and Ubuntu.
+- Run the Linux setup steps inside WSL.
+
+2) Install Arcane Agents globally.
+
+```bash
+npm install -g arcane-agents
+```
+
+3) Create your user config.
+
+```bash
+arcane-agents init
+```
+
+`arcane-agents start` also auto-creates a starter config if it is missing.
+
+4) Edit your config.
+
+```bash
+arcane-agents config edit
+```
+
+This opens `~/.config/arcane-agents/config.yaml` in `$VISUAL` or `$EDITOR`.
+
+5) Run setup checks.
+
+```bash
+arcane-agents doctor
+```
+
+6) Start Arcane Agents.
+
+```bash
+arcane-agents
+```
+
+7) Open `http://127.0.0.1:7600`.
+
+Optional maintenance commands:
+
+```bash
+npm install -g arcane-agents@latest  # upgrade
+npm uninstall -g arcane-agents       # uninstall
+```
+
+## Run Locally (Developers)
+
+1) Install system dependencies.
+
+Linux (Debian/Ubuntu):
+
+```bash
+sudo apt update
+sudo apt install -y tmux git
+```
+
+macOS (Homebrew):
+
+```bash
+brew install tmux git
+```
+
+Windows:
+
+- Install WSL2 and Ubuntu.
+- Run the Linux setup steps inside WSL.
+
+2) Clone and install dependencies.
+
+```bash
+git clone https://github.com/thomasrice/arcane-agents.git
+cd arcane-agents
+npm install
+```
+
+3) Create your user config.
+
+```bash
+npm run cli -- init
+```
+
+4) Edit your config.
+
+```bash
+npm run cli -- config edit
+```
+
+Or edit `~/.config/arcane-agents/config.yaml` directly.
+
+5) Start dev mode (client + server).
+
+```bash
+npm run dev
+```
+
+Default URLs:
+
+- App (Vite): `http://127.0.0.1:7600`
+- API (Express): `http://127.0.0.1:7601`
+
+## How To Use
+
+- Use shortcut buttons in the bottom bar to quickly spawn agents.
+- Use the `+` button for custom spawn (project + runtime selection).
+- Click an agent to focus it and attach the terminal panel.
+- Drag agents on the map to organize them visually.
+- Use contextual controls to stop/restart selected agents.
+
+## Keyboard Guide
+
+### Selection vs terminal focus
+
+- `Selection` focus: map/roster shortcuts are active.
+- `Terminal` focus: keys go directly to the attached terminal.
+- `Enter` on a selected agent focuses its terminal.
+- With no selection, `Enter` activates the highlighted roster item; press `Enter` again to focus terminal input.
+- `Ctrl+D` or `Ctrl+]` exits terminal focus back to selection focus.
+- Press `Ctrl+D` or `Ctrl+]` again in selection focus to clear selection.
+
+### Common shortcuts
+
+- `/`: open command palette.
+- `?`: show the full shortcut list in-app.
+- `Tab` / `Shift+Tab`: cycle agents (or cycle selected-group focus).
+- `.` / `,` / `Shift+.`: cycle idle agents.
+- `1-0`: select control group.
+- `Ctrl+1-0`: assign selected agents to a control group.
+- `K`: open kill confirmation for selected agents.
+- `Shift+K`: kill highlighted roster agent (then `Enter` to confirm).
+- `R`: rename selected agent.
+- `M`: toggle movement mode for selected agent(s).
+- `W/A/S/D` or arrow keys: move selected agents.
+- `Shift+W/A/S/D` or `Shift+Arrow keys`: pan the map viewport.
+- `-` / `+`: zoom map out or in (outside terminal focus).
+- `[` / `]`: resize split; `Shift+[` / `Shift+]`: jump split to edge; `=`: reset split.
+- Left-drag the divider between map and terminal panes to resize.
+- `Esc`: close overlays/dialogs, then deselect.
+
+## Configuration
+
+### Paths and merge order
+
+- Primary config: `~/.config/arcane-agents/config.yaml`
+- Optional override config: `~/.config/arcane-agents/config.local.yaml`
+- State directory: `~/.local/state/arcane-agents/`
+- SQLite DB: `~/.local/state/arcane-agents/arcane-agents.db`
+
+Config is loaded at server startup and merged in this order:
+
+1. Built-in defaults
+2. `config.yaml`
+3. `config.local.yaml`
+
+Changes require a server restart.
+
+### Config CLI helpers
+
+```bash
+arcane-agents config path  # print config and local override paths
+arcane-agents config show  # print config.yaml
+arcane-agents config edit  # open config.yaml in $VISUAL/$EDITOR
+```
+
+### Top-level sections
+
+- `projects`: named working directories (`cwd`) agents can launch into.
+- `runtimes`: command presets to run in a project directory.
+- `shortcuts`: saved `project + runtime` combinations; can also include hotkeys.
+- `discovery`: optional auto-discovery rules for additional projects.
+- `avatars`: avatar selection settings (for example disabling specific avatar types from random allocation).
+- `audio`: client sound settings.
+- `backend.tmux`: tmux session and status poll settings.
+- `server`: API bind host/port.
+
+### Quick example (Claude Code + OpenCode)
+
+If you want to launch Claude Code in `~/minotaur/taurient` and OpenCode in
+`~/code/personal-assistant`, a minimal config looks like this:
+
+```yaml
+projects:
+  home:
+    path: "~"
+    shortName: home
+  taurient:
+    path: ~/minotaur/taurient
+    shortName: taur
+  personal-assistant:
+    path: ~/code/personal-assistant
+    shortName: pa
+
+runtimes:
+  claude:
+    command: ["claude"]
+    label: Claude Code
+  opencode:
+    command: ["opencode"]
+    label: OpenCode
+  shell:
+    command: ["bash"]
+    label: Shell
+
+shortcuts:
+  - label: Taurient Claude
+    project: taurient
+    runtime: claude
+    hotkeys: ["Ctrl-U"]
+  - label: PA OpenCode
+    project: personal-assistant
+    runtime: opencode
+    hotkeys: ["Ctrl-A"]
+  - label: Home Shell
+    project: home
+    runtime: shell
+    hotkeys: ["Ctrl-S"]
+```
+
+### `projects`
+
+`projects` is a map keyed by project id. Each entry defines the working
+directory used when launching an agent.
+
+Required fields per project:
+
+- `path`: filesystem path (supports `~` expansion)
+- `shortName`: short display slug
+
+Optional fields per project:
+
+- `label`: UI-friendly label
+
+Example:
+
+```yaml
+projects:
+  app:
+    path: ~/code/my-app
+    shortName: app
+    label: My App
+```
+
+### `runtimes`
+
+`runtimes` is a map keyed by runtime id. Each runtime defines the command Arcane
+Agents runs inside a selected project directory.
+
+Required fields per runtime:
+
+- `command`: command to execute (string array)
+- `label`: UI label
+
+Example:
+
+```yaml
+runtimes:
+  claude:
+    command: ["claude"]
+    label: Claude Code
+  shell:
+    command: ["bash"]
+    label: Shell
+```
+
+### `shortcuts`
+
+`shortcuts` is an array of saved launch recipes. Each shortcut combines a
+`project` with a `runtime`, and can optionally include one or more keyboard
+hotkeys.
+
+Required fields per shortcut:
+
+- `label`: button text
+- `project`: project id (or unique `shortName`)
+- `runtime`: runtime id
+
+Optional fields per shortcut:
+
+- `command`: command override for this shortcut only
+- `hotkeys`: array of key chords (for example `"Ctrl+1"`)
+- `avatar`: pinned avatar type
+
+Example:
+
+```yaml
+shortcuts:
+  - label: APP
+    project: app
+    runtime: claude
+    hotkeys: ["Ctrl+1"]
+  - label: Tests
+    project: app
+    runtime: shell
+    command: ["npm", "test", "--", "--watch"]
+    avatar: elder-wizard
+```
+
+### `discovery`
+
+`discovery` is an array of rules with:
+
+- `name` (required)
+- `type` (required): `worktrees`, `directories`, or `glob`
+- `path` (required)
+- `match` (optional)
+- `exclude` (optional)
+- `maxDepth` (optional)
+
+Rule behavior:
+
+- `worktrees`: runs `git worktree list` from `path`.
+- `directories`: recursively scans directories from `path`.
+  - `match` checks for a marker path (for example `.git`).
+  - `exclude` skips matching directory names.
+  - `maxDepth` controls recursion depth.
+- `glob`: treats `path` as a glob pattern and includes matching directories.
+
+Example:
+
+```yaml
+discovery:
+  - name: code-projects
+    type: directories
+    path: ~/code
+    match: ".git"
+    exclude: ["node_modules", ".cache", "dist"]
+    maxDepth: 2
+  - name: app-worktrees
+    type: worktrees
+    path: ~/code/my-app
+  - name: playground-glob
+    type: glob
+    path: ~/code/playground/*
+```
+
+### `backend.tmux`
+
+- `sessionName`: tmux session used for managed windows.
+- `pollIntervalMs`: status poll interval in milliseconds (minimum `250`).
+
+Example:
+
+```yaml
+backend:
+  tmux:
+    sessionName: arcane-agents
+    pollIntervalMs: 2500
+```
+
+### `audio`
+
+- `enableSound`: enable or disable in-app voice/sound playback (default `true`).
+
+Example:
+
+```yaml
+audio:
+  enableSound: true
+```
+
+### `avatars`
+
+- `disabled`: avatar folder names to exclude from random avatar allocation.
+- Disabled avatars can still be used when explicitly pinned via `shortcuts[].avatar`.
+
+Example:
+
+```yaml
+avatars:
+  disabled:
+    - minotaur-strategist
+    - gothic-witch
+```
+
+### `server`
+
+- `host`: bind address for the API server.
+- `port`: bind port for the API server.
+
+Example:
+
+```yaml
+server:
+  host: 127.0.0.1
+  port: 7600
+```
+
+## Development Commands
+
+```bash
+npm run dev        # client + server
+npm run dev:server # backend only
+npm run dev:client # frontend only
+npm run lint
+npm run typecheck
+npm run test:ci
+```
+
+## Build + Run
+
+```bash
+npm run build
+npm start
+```
+
+Default runtime URL: `http://127.0.0.1:7600`
+
+Health checks:
+
+```bash
+# dev mode (npm run dev)
+curl http://127.0.0.1:7601/api/health
+
+# built app (npm start, default config)
+curl http://127.0.0.1:7600/api/health
+```
+
+## Status Debugging
+
+To log status transitions (for example `working -> idle`) in the server terminal, set
+`ARCANE_AGENTS_STATUS_TRACE` when launching the backend:
+
+```bash
+ARCANE_AGENTS_STATUS_TRACE=transitions npm run dev:server
+```
+
+Useful modes:
+
+- `ARCANE_AGENTS_STATUS_TRACE=off` (default)
+- `ARCANE_AGENTS_STATUS_TRACE=transitions` (only status changes; no output when status stays the same)
+- `ARCANE_AGENTS_STATUS_TRACE=verbose` (every status evaluation)
+
+If you run full dev mode:
+
+```bash
+ARCANE_AGENTS_STATUS_TRACE=transitions npm run dev
+```
+
+Status debugging APIs:
+
+- `GET /api/status-debug`
+- `GET /api/workers/:workerId/status-debug`
+- `GET /api/workers/:workerId/status-history`
+
+## Stack
+
+- TypeScript (client + server)
+- Vite + React (client)
+- Express + ws (server)
+- xterm.js (embedded terminal)
+- node-pty (PTY bridge)
+- tmux (session/window process management)
+- better-sqlite3 (local persistence)
+
+## Project Layout
+
+```text
+src/
+  client/   UI, map renderer, xterm terminal panel
+  server/   API, orchestration, tmux adapter, status monitor
+  shared/   Shared types/config models
+assets/     Maps, character art
+```
+
+## Customizing Avatars
+
+Avatar packs are directory-driven under `assets/characters/<avatar-type>/`.
+
+- Required sprite files are documented in `assets/characters/README.md`.
+- Optional voice clips are loaded from `assets/characters/<avatar-type>/voice-lines/`.
+- Voice file names: fixed events use `arrive.mp3`, `attention.mp3`, `complete.mp3`, `death.mp3`; random events match any `move*.mp3` and `selected*.mp3` clips in the folder.
+- In app runtime, clips are served from `/api/assets/characters/<avatar-type>/voice-lines/<file>.mp3`.
+- Add a new avatar by dropping in a compliant folder; it becomes available automatically.
+
+## License
+
+- Licensed under MIT.

package/assets/characters/README.md

@@ -0,0 +1,114 @@
+# Character Sprite Assets
+
+Arcane Agents loads character sprites directly from this directory.
+
+## Ownership + License
+
+- Character image assets in this repo are Copyright (c) 2026 Thomas Rice.
+- Assets in this repository are included under the MIT license.
+
+## Expected Format
+
+- Frame size: `64x64` PNG per frame.
+- Directions: `south`, `east`, `north`, `west`.
+- Variable walk frame counts are supported per direction and per character.
+- Missing assets fall back to simple Canvas circles/shapes.
+
+## Directory Layout
+
+```text
+assets/characters/
+  knight/
+    rotations/
+      south.png
+      east.png
+      north.png
+      west.png
+    animations/
+      walk/
+        south/
+          0.png
+          1.png
+          ...
+        east/
+          0.png
+          1.png
+          ...
+        north/
+          0.png
+          1.png
+          ...
+        west/
+          0.png
+          1.png
+          ...
+      working/
+        0.png
+        1.png
+        ...
+        15.png
+    voice-lines/              # optional
+      arrive.mp3
+      move_variant_1.mp3      # optional random move variant
+      move_variant_2.mp3      # optional random move variant
+      move_variant_3.mp3      # optional random move variant
+      attention.mp3
+      complete.mp3
+      death.mp3
+      selected_variant_1.mp3  # optional random selection variant
+      selected_variant_2.mp3  # optional random selection variant
+      selected_variant_3.mp3  # optional random selection variant
+```
+
+Create one top-level folder per character type.
+
+Avatar discovery is directory-driven: Arcane Agents treats each subfolder as an available avatar when these required files exist:
+
+- `rotations/south.png`
+- `rotations/east.png`
+- `rotations/north.png`
+- `rotations/west.png`
+- `animations/walk/south/0.png`
+- `animations/working/0.png`
+
+If these files are present, you can drop in a new folder and it becomes eligible automatically (including random spawn selection).
+
+## Optional Voice Lines
+
+Character packs can include optional voice clips in `voice-lines/`.
+
+- `arrive.mp3`: plays when a worker first spawns.
+- `move*.mp3`: random pick when a manual move order is issued.
+- `attention.mp3`: plays when status changes to `attention`.
+- `complete.mp3`: plays when status changes from `working` to `idle`.
+- `death.mp3`: plays when a worker is removed.
+- `selected*.mp3`: random pick when a worker becomes newly selected.
+
+Selection audio only triggers on a real selection change. Clicking the currently selected worker again does not replay the selection line.
+Move and selection audio use filename prefix matching. Any `move*.mp3` or `selected*.mp3` clip in the directory is eligible.
+
+## Runtime Behavior
+
+- Idle/static rendering uses `rotations/<direction>.png`.
+- Moving characters use `animations/walk/<direction>/<index>.png` frames.
+- Working characters use `animations/working/<index>.png` (south-facing loop).
+- Frames are loaded in ascending index order starting at `0.png` until a gap is encountered.
+
+## Generation Notes (Recorded)
+
+We do not currently have a checked-in generator preset export or prompt/options log.
+
+What we can reliably recover from the current asset set:
+
+- All character sprites are `64x64` PNG (`402/402` files).
+- Direction set is always `south`, `east`, `north`, `west`.
+- Walk cycle length is variable by character (legacy packs often `6` frames, newer packs often `8` frames).
+- Standard working cycle is `16` frames (`0.png` to `15.png`).
+- One known outlier: `rogue` has `12` south walk frames.
+- Existing characters share a consistent top-down fantasy RPG style with transparent backgrounds.
+
+Recommended process for future consistency:
+
+1. When generating a new character, copy the exact generation options/prompt into this file.
+2. Include model, seed (if available), and any style sliders/toggles.
+3. Keep output at `64x64` and preserve the same direction/frame layout.