Getting Started

Get Relaygent running in under two minutes.

terminal

git clone https://github.com/prestoj/relaygent.git
cd relaygent
./setup.sh
relaygent start

Setup handles everything: dependency installation, hub build, Hammerspoon configuration, and Claude CLI authentication. Open http://localhost:8080 to see the dashboard.

Warning: This gives Claude full, unsupervised control of your machine. Only run on a dedicated machine or VM you're comfortable handing over.

Recommended Setup

Relaygent works best when you treat each agent like a remote team member with their own workspace and identity.

Dedicated Hardware

Give each agent its own machine — a Mac Mini, Linux box, or cloud VM. The agent uses the screen, keyboard, and filesystem, so sharing your daily driver will interfere with both of you. If dedicated hardware isn't an option, a VM on an always-on machine works too.

Network Access

Access your agent's dashboard over the network. Tailscale is the easiest way — it creates a private mesh VPN with zero config. Once connected, open http://<agent-hostname>:8080 from your laptop, phone, or tablet.

Multiple Agents

Two agents are more than the sum of their parts. They review each other's code, split work, and catch each other's mistakes. Set up Slack for real-time coordination and Linear for task tracking — the agents will use both to self-organize and avoid duplicating work.

Agent Identity

Give each agent its own email address, GitHub account, and API credentials. A dedicated email is the gateway to most online services — it lets the agent sign up for APIs, receive notifications, and interact with services independently.

Tool Integration

Relaygent ships with native Slack, Gmail, GitHub, and Linear integrations. For other systems — Microsoft Teams, ClickUp, Jira, Notion, or anything with an API — ask your agent to build the bridge. It can write custom MCP servers, configure webhooks, and set up whatever it needs.

Clear Intent

Your INTENT.md file is the agent's north star. It reads this every session but can never edit it. Be specific about what you want and how you want it done — the agent will follow your direction across hundreds of sessions.

Requirements

Dependency	Version	Notes
macOS or Linux	macOS 13+ / Ubuntu 22.04+	Primary supported platforms
Node.js	20+	Dashboard, services, MCP servers
Python	3.9+	Relay harness, notifications
Claude Code	Latest	`npm install -g @anthropic-ai/claude-code`
git	Any	KB tracking, PR workflow

Platform extras

macOS: Hammerspoon (setup installs via Homebrew). You'll need to grant Accessibility and Screen Recording permissions.

Linux:

terminal

sudo apt install xdotool scrot wmctrl imagemagick python3-pyatspi at-spi2-core

Setup Guide

The interactive setup wizard walks you through everything. Here's what happens at each step:

Prerequisite check — verifies Node.js 20+, Python 3.9+, git, and Claude Code are installed and authenticated.
Directory creation — creates ~/.relaygent/ for config, knowledge/topics/ for the KB, logs/ and data/ for runtime state.
KB templates — copies starter templates (HANDOFF.md, INTENT.md, tasks.md, etc.) and initializes a git repo for change tracking.
Dependencies — runs npm install for hub, notifications, computer-use, email, slack, and secrets. Creates a Python venv for notifications.
Hub build — compiles the SvelteKit dashboard.
CLAUDE.md — generates a machine-specific context file with paths, ports, and service info that gets injected into every Claude session.
Secrets — optionally stores email credentials in ~/.relaygent/secrets.json.
Slack — optionally configures Slack integration with bot and app tokens.
Hammerspoon (macOS) — installs Hammerspoon, copies Lua scripts, guides you through permissions.
Hooks & MCP — registers PostToolUse hooks and MCP servers with Claude Code.
CLI symlink — creates ~/bin/relaygent so the CLI is on your PATH.

CLI Reference

All commands are available via the relaygent CLI after setup.

relaygent start

Launch the agent, dashboard, notifications, and all services. Registers LaunchAgents (macOS) or starts background processes.

relaygent stop

Stop all services and the relay agent.

relaygent restart

Restart all services.

relaygent status

Show what's running — hub, notifications, relay, Hammerspoon.

relaygent logs [service]

View service logs. Use -f to follow, -n for line count, --list to see available services. Supports fuzzy matching on service names.

relaygent orient

Quick system status: services, disk, recent commits, agent work, tasks due.

relaygent check

Diagnose configuration, verify file permissions, check service health.

relaygent health

Quick health check — pings all services and reports status.

relaygent update

Pull latest code, rebuild the hub, and restart all services. Safely stashes uncommitted changes and restores them after.

relaygent set-password

Set or remove password authentication for the hub dashboard. Use --remove to disable.

relaygent archive-linear

Archive completed/canceled Linear issues older than 7 days. Supports --dry-run and --days N.

relaygent setup

Run the interactive setup wizard. Installs dependencies, builds the hub, configures services.

relaygent open [page]

Open the hub dashboard in your browser. Optionally specify a page: relaygent open kb.

relaygent mcp list|add|remove|test

Manage MCP servers. Add custom servers with --env flags, test connectivity, or list all configured servers.

relaygent cleanup

Free disk space by removing old session data, Chrome caches, and logs. Supports --dry-run and --days N. Never deletes the most recent session.

relaygent clean-logs

Remove old and rotated log files. Supports --dry-run and --days N.

relaygent stats

Show session metrics — duration, tool calls, context usage, and more.

relaygent changelog [--days N]

Show merged PRs and recent commits. Defaults to last 7 days.

relaygent digest [--days N]

Generate a daily summary: PRs merged, commits, disk usage, open PRs.

relaygent test [suite]

Run the test suite. Optionally specify a suite: hub, harness, notifications, etc.

relaygent install-services

Set up auto-restart services for all daemons. Installs LaunchAgents on macOS or systemd user services on Linux.

relaygent completions

Output shell completions for bash/zsh. Add to your shell: eval "$(relaygent completions)".

relaygent version

Show version info (git commit and date).

Dashboard

The hub is a SvelteKit web app at http://localhost:8080 with live updates via WebSocket.

Activity Feed

Every tool call the agent makes, in real time. Expand any entry to see full input/output details.

Screen View

Collapsible live view of what the agent sees via Hammerspoon screenshots. Click to interact.

Chat

Message your agent from the dashboard. Messages wake the agent from sleep. The agent responds in the same chat.

Sessions

Browsable history grouped by date with search filtering. Each session shows stats, tool breakdown, duration, and AI-generated summaries.

Knowledge Base

Browse, create, edit, and delete the agent's long-term memory. Markdown with wiki-links, rendered in the browser.

Context Bar

Shows how full the current session's context window is. At ~85%, the agent begins handoff.

Current Tasks

Live task list showing what the agent is working on right now, with status indicators for pending, in-progress, and completed items.

Agent Tasks

Real-time display of the agent's current task list, pulled from Claude Code's TodoWrite tool via WebSocket.

Open PRs

Shows open pull requests with review status badges — approved, pending, or changes requested.

Notifications

Aggregated notifications from Slack, GitHub, Linear, email, and reminders. Auto-hides when empty.

Command Palette

Press Cmd+K to open a searchable overlay. Quickly navigate to any page or search KB topics.

Authentication

Optional password protection. Enable with relaygent set-password. Protects all routes including WebSocket and file uploads.

Tip: Since the agent uses the desktop, you'll typically access the hub from another computer on the same network — navigate to the machine's IP on port 8080.

How the Relay Works

Start a session — the harness launches Claude Code with a system prompt, handoff notes from the previous session, and your intent file.
Agent works — Claude reads files, writes code, runs commands, uses the screen — whatever the task requires.
PostToolUse hook fires — after every tool call, a hook injects current time, notifications, and context usage percentage.
Context fills up — at ~85%, the agent wraps up: writes a detailed handoff, updates persistent state, and commits the KB.
Successor continues — the harness spawns a fresh session that reads the handoff and continues immediately.
Sleep between tasks — the harness polls for notifications and resumes when one arrives. Zero token cost while sleeping.

Computer Use

The agent interacts with your screen through 33 MCP tools across several categories:

Screen

Screenshots (full or cropped), click, double-click, right-click, type, scroll, drag. All with modifier key support.

Accessibility

Read the accessibility tree, find elements by role or title, click elements programmatically. Works with any native UI.

Apps & Windows

Launch apps, focus windows, list all visible windows with positions.

Browser (14 tools)

Navigate, click, type, fill forms, hover, select dropdowns, scroll, wait for elements, read text, evaluate JS, get URLs — all via Chrome DevTools Protocol.

System

AppleScript (macOS), dismiss dialogs, reload Hammerspoon config.

On macOS, these are backed by Hammerspoon. On Linux, they use xdotool, scrot, ImageMagick, wmctrl, and pyatspi2. Every action auto-returns a screenshot so the agent sees results immediately.

Knowledge Base

The agent maintains a git-tracked KB that grows across sessions:

File	Purpose
`MEMORY.md`	Persistent memory — accumulates across sessions, auto-injected into every prompt
`HANDOFF.md`	Briefing from the previous session (rewritten from scratch each handoff)
`INTENT.md`	Your priorities — the agent reads this but never edits it
`tasks.md`	Recurring and one-off task queue
`curiosities.md`	Open questions to explore when idle

Create additional topic files as needed. The agent links them together with [[wiki-links]]. All changes are committed to a local git repo for version history.

Hooks & Notifications

The agent stays aware through a PostToolUse hook — a shell script that runs after every tool call:

Current time — injected every call so the agent always knows what time it is
Context tracking — calculates context window fill %. At 85%, injects a wrap-up warning
Chat messages — checks for unread messages from you
Reminders — the agent can set reminders via MCP tools; when they fire, the hook surfaces them

A background notification poller caches results to a temp file. The hook reads from cache (instant, no HTTP) — zero latency added to tool calls.

Wake sources

The agent wakes from sleep when any of these fire:

Hub chat messages — sent from the dashboard
Slack messages — real-time via Socket Mode (DMs and channel mentions)
Email — polled via Gmail API
GitHub notifications — PR reviews, comments, mentions, assignments
Reminders — one-shot or recurring, set by the agent itself

Integrations

Slack

Connect the agent to Slack with bot and app tokens. It can read/send messages, search, react, and list channels. Real-time delivery via Socket Mode — no webhooks or public URLs needed. Configure during setup or later via ~/.relaygent/slack/.

Email (Gmail)

The agent gets its own email via Gmail OAuth2. Tools: search, read, send, draft, modify labels. Setup: create an OAuth2 client in Google Cloud Console, save keys to ~/.relaygent/gmail/gcp-oauth.keys.json, then run node email/setup-gmail.mjs.

GitHub

The agent wakes when PRs are reviewed, commented on, or assigned. Notifications are collected automatically via the gh CLI — just run gh auth login and it works. No additional configuration needed.

Linear

Task management via Linear API. The agent can list, create, update, and archive issues. Get an API key from Linear settings and save to ~/.relaygent/linear/api-key.

Wake Sources

The agent sleeps at zero token cost between active work. It wakes on: chat messages, Slack DMs/mentions, GitHub notifications, Linear updates, email, and scheduled reminders.

Architecture

project structure

relaygent/
├── harness/          # Relay runner — session lifecycle, sleep/wake
├── hub/              # SvelteKit dashboard + chat + KB (Node.js)
├── computer-use/     # MCP server for screen control (33 tools)
├── hammerspoon/      # Lua scripts for macOS screen control
├── notifications/    # Reminder + wake trigger service (Python)
├── linear/           # Linear MCP server + auto-archive
├── email/            # Gmail MCP server (OAuth2, 6 tools)
├── slack/            # Slack MCP server + Socket Mode listener
├── secrets/          # Credential store (dotfile JSON + MCP)
├── hooks/            # PostToolUse hook (time, context, messages)
├── templates/        # Starter KB files for new installations
├── setup/            # Interactive onboarding wizard
├── scripts/          # Service installers (LaunchAgents, systemd)
└── bin/relaygent     # CLI entry point

Key services

Service	Port	Technology
Hub dashboard	8080	SvelteKit + WebSocket
Notifications	8083	Python / Flask
Hammerspoon	8097	Lua HTTP server

Troubleshooting

Hub shows 500 errors after update

Never run npm run build directly — the running server will serve stale manifests. Always use relaygent update which rebuilds and restarts atomically.

Port 8080 is already in use

Another process is holding the port. Run relaygent stop first, or check with lsof -i :8080. On macOS, the LaunchAgent auto-restarts the hub, so kill the process and it will respawn cleanly.

Hammerspoon permissions (macOS)

Hammerspoon needs Accessibility and Screen Recording permissions. Go to System Settings → Privacy & Security → Accessibility (and Screen Recording) and enable Hammerspoon. You may need to restart it after granting permissions.

Chrome CDP not connecting

Chrome requires a non-default --user-data-dir for remote debugging to work. The setup creates one at ~/data/chrome-debug-profile. If Chrome is already running with the default profile, the debug port won't activate. Close Chrome and let the agent launch it with the correct flags.

Agent not waking from sleep

Check that the notifications service is running: relaygent health. The notification poller must be active for sleep/wake to work. If it's down, relaygent restart will bring it back.

Changes to code not taking effect

MCP servers cache code at startup. After editing source files, restart the Claude Code session for MCP changes to take effect. For hub changes, use relaygent update.