corsa

A Terminal User Interface (TUI) for managing multiple local development processes. View real-time logs, monitor status, and control all your dev servers from a single dashboard.

Built with OpenTUI.

Why corsa?

When working on a full-stack project, you often need to run multiple processes simultaneously—a frontend dev server, a backend API, database containers, workers, etc. corsa gives you:

• Single dashboard for all your processes with tabbed log viewing
• Real-time logs with search and ANSI color support
• Status monitoring to see at a glance what's running, stopped, or crashed
• Health checks to monitor service availability
• AI integration via MCP to let your IDE assistant read logs and control processes

Installation

Homebrew (macOS and Linux)

brew install tomagranate/tap/corsa

NPM

npm install -g @tomagranate/corsa

curl (macOS and Linux)

curl -fsSL https://raw.githubusercontent.com/tomagranate/corsa/main/install.sh | bash

Manual Download

Download the latest binary for your platform from Releases.

Platform	Download
macOS (Apple Silicon)	corsa-darwin-arm64.tar.gz
macOS (Intel)	corsa-darwin-x64.tar.gz
Linux (x64)	corsa-linux-x64.tar.gz
Linux (ARM64)	corsa-linux-arm64.tar.gz
Windows (x64)	corsa-windows-x64.zip

Quick Start

1. Create a config file in your project:

corsa init

2. Edit corsa.config.toml to add your processes:

[[tools]]
name = "frontend"
command = "npm"
args = ["run", "dev"]
cwd = "./frontend"

[[tools]]
name = "backend"
command = "python"
args = ["-m", "uvicorn", "main:app", "--reload"]
cwd = "./backend"

3. Start the dashboard:

corsa

4. Optional: install the corsa AI skill from this repository:

npx skills add tomagranate/corsa

CLI Reference

Commands

Command	Description
corsa	Start the TUI dashboard
corsa init	Create a sample config file in the current directory
corsa mcp	Start the MCP server for AI agent integration
corsa ctl <subcommand>	Control running processes through the MCP API

Options

Option	Description
-c, --config <path>	Path to config file (default: corsa.config.toml)
-h, --help	Show help message
-v, --version	Show version information

ctl Subcommands

Subcommand	Description
corsa ctl list	List all processes with status and recent logs (ps/ls aliases)
corsa ctl logs <name>	Get recent logs for a process
corsa ctl stop <name>	Stop a running process (rm alias)
corsa ctl restart <name>	Restart a process
corsa ctl clear <name>	Clear process logs
corsa ctl send-keys <name> --key <value>	Send keypresses/text to an interactive process
corsa ctl reload	Reload config and restart processes

Examples

# Start with default config
corsa

# Use a custom config file
corsa --config ./configs/dev.toml
corsa -c ./configs/dev.toml

# Create a new config file
corsa init

# Start MCP server for AI integration
corsa mcp

# List processes via CLI control API
corsa ctl list
corsa ctl ls

# Read logs with filtering
corsa ctl logs backend --lines 200 --search ERROR --search-type substring

# Stop a process (alias)
corsa ctl rm backend

# Send interactive input
corsa ctl send-keys repl --key "help" --key return

# Machine-readable output for agents/scripts
corsa ctl list --json

Configuration

corsa is configured via a TOML file. By default, it looks for corsa.config.toml in the current directory.

Minimal Example

[[tools]]
name = "server"
command = "npm"
args = ["run", "dev"]

Full Example

[home]
enabled = true
title = "My Project"

[ui]
theme = "mist"
showTabNumbers = true

[mcp]
enabled = true

[[tools]]
name = "web"
command = "npm"
args = ["run", "dev"]
cwd = "./web"
description = "Next.js frontend"

[tools.ui]
label = "Open App"
url = "http://localhost:3000"

[tools.healthCheck]
url = "http://localhost:3000/api/health"
interval = 5000

[[tools]]
name = "api"
command = "cargo"
args = ["watch", "-x", "run"]
cwd = "./api"
description = "Rust API server"
cleanup = ["pkill -f 'target/debug/api'"]

[tools.env]
RUST_LOG = "debug"

For a complete reference of all configuration options, see the sample config file.

Themes

corsa includes several built-in themes. Set in your config:

[ui]
theme = "mist"

Available themes: default (Moss), mist, cappuccino, synthwave, terminal (auto-detect from your terminal).

MCP Integration

corsa can expose an HTTP API for AI agents (Cursor, Claude, etc.) via the Model Context Protocol.

Enable in Config

[mcp]
enabled = true
port = 18765

Configure Your IDE

Add to your MCP configuration (e.g., ~/.cursor/mcp.json):

{
  "mcpServers": {
    "corsa": {
      "command": "corsa",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools

Tool	Description
list_processes	List all processes with status, health, and last 20 log lines
get_logs	Get recent logs (supports search and line limits)
stop_process	Stop a running process
restart_process	Restart a process
clear_logs	Clear logs for a process
send_keys	Send virtual keypresses to an interactive process
reload_config	Reload config file and restart all processes

Contributing

See the Contributing Guide for development setup and guidelines.

License

MIT