Ragna

Agent management server with web interface for running Claude CLI agents on your machine.

Features

• Run background agents using Claude CLI on selected projects
• Web interface to manage and monitor agents
• Real-time output streaming via WebSocket
• Project management (add multiple project directories)
• Clean, simple UI with agent list sidebar and chat interface

Prerequisites

• Node.js (v18 or higher)
• Claude CLI installed and configured (npm install -g @anthropic-ai/claude-cli)
• OpenCode (optional, can be auto-started by the server): npm install -g opencode

Installation

# Install dependencies for both server and client
npm run setup

Development

Run both server and client in development mode:

npm run dev

This will start:

• Server on http://localhost:3001
• Client on http://localhost:3000

Run individually

# Server only
npm run dev:server

# Client only
npm run dev:client

Production

# Build client
npm run build

# Start server (serves built client)
npm start

Usage

1. Open http://localhost:3000 in your browser
2. Add a project by clicking "+ Add" and entering the project name and path
3. Select a project from the dropdown
4. Enter instructions for the agent in the textarea
5. Click "Start Agent" to launch a new agent
6. View agent output in real-time
7. Stop agents using the "Stop" button in the agent list

Project Structure

ragna/
├── server/
│   ├── index.js          # Express server with WebSocket support
│   └── agentManager.js   # Agent lifecycle management
├── client/               # React frontend
│   ├── src/
│   │   ├── App.jsx      # Main UI component
│   │   └── App.css      # Styles
│   └── vite.config.js
└── package.json

Configuration

Environment Variables

The server supports the following environment variables:

• PORT - Server port (default: 3001)
• HOST - Server host (default: 0.0.0.0)
• OPENCODE_PORT - OpenCode server port (default: 4096)
• OPENCODE_ENABLED - Enable/disable automatic OpenCode server startup (default: true)

Example:

# Disable OpenCode auto-start (if you want to run it manually)
OPENCODE_ENABLED=false npm start

# Change OpenCode port
OPENCODE_PORT=5000 npm start

OpenCode Server Management

The Ragna server can automatically start and manage an OpenCode server for you. When enabled (default), the server will:

1. Spawn an OpenCode server process on startup (port 4096 by default)
2. Forward OpenCode stdout/stderr to the console
3. Gracefully shut down the OpenCode server on exit (SIGTERM/SIGINT)
4. Restart OpenCode if the main server is restarted

Benefits:

• No need to manually start OpenCode in a separate terminal
• OpenCode lifecycle is tied to the Ragna server
• Easier deployment and development workflow

Manual OpenCode Server: If you prefer to manage OpenCode manually, disable auto-start:

OPENCODE_ENABLED=false npm run dev

Then start OpenCode separately:

opencode serve --port 4096

Data Storage

Projects are stored in ~/.ragna/projects.json and persist across restarts.

API Endpoints

REST API

• GET /api/agents - List all agents
• POST /api/agents - Start a new agent
• DELETE /api/agents/:id - Stop an agent
• GET /api/projects - List projects
• POST /api/projects - Add a new project

WebSocket Messages

Client → Server:

• { type: 'get_agents' } - Request agent list
• { type: 'start_agent', prompt: string, projectPath: string } - Start agent
• { type: 'stop_agent', agentId: string } - Stop agent

Server → Client:

• { type: 'agents', data: Agent[] } - Agent list
• { type: 'agent_started', data: Agent } - Agent started
• { type: 'agent_stopped', data: { agentId: string } } - Agent stopped
• { type: 'agent_output', data: { agentId: string, output: Output } } - New output
• { type: 'agent_error', data: { agentId: string, error: string } } - Error occurred