convez.ai
AgenteDevOps & InfraestruturaAvançado
caopulan

Runlight - Monitor de Agentes IA

caopulan/AgentMonitor

Observabilidade passiva para sessões de agentes IA com dashboard centralizado

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de observabilidade passiva para monitorar execução de tarefas de agentes IA como Codex e Claude Code de um único dashboard. Registra eventos do ciclo de vida (inicialização, heartbeats, atividades de ferramentas, falhas) sem interferir na operação do agente. Suporta backends locais e serverless com fila durável, inferência de status em tempo real e visualização em dashboard React ou menu bar do macOS.

Instalação

$npx convez-ai caopulan/AgentMonitor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
25%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Monitorar múltiplos agentes IA em execução simultânea
  • Diagnosticar falhas e timeouts de agentes sem instrumentação invasiva
  • Rastrear atividade de ferramentas e comandos em diferentes máquinas e branches
  • Visualizar status em tempo real (rodando, aguardando, travado, falho) em painel unificado

Veredito

Solução madura de observabilidade para engenheiros que executam múltiplos agentes IA em produção. Arquitetura robusta com suporte a backends local/serverless, mas requer familiaridade com TypeScript, Python e deployment. Essencial para times que precisam visibilidade operacional em agentes Codex/Claude Code.

README

A tradução para o português deste README ainda está na fila.

Runlight

Runlight records lifecycle events from Codex, Claude Code, and custom agent adapters without taking control of the agent. It stores session starts, heartbeats, tool and command activity, prompts, permission waits, completions, failures, and aborts behind one shared API.

Use it when you want to see which agents are running, waiting, stale, finished, or failed across projects, machines, branches, and sessions. The repository contains local and serverless backends, a React dashboard, a macOS menu bar viewer, packaged Codex and Claude Code integrations, and a Python adapter for custom clients.

Features

  • Daemon-first local ingestion for Codex and Claude Code
  • npm-installed runlight CLI with one-command setup, login, status, health, settings, and plugin installation commands
  • Local durable queue for hook events before upload
  • Shared event protocol for all agent adapters
  • Live session status inference from real events and heartbeats
  • Project-grouped dashboard with session pins, branches, machines, and paths
  • Message-style run feed plus per-session event timelines
  • Embedded local server and static dashboard for single-machine use
  • Local FastAPI server with SQLite by default and PostgreSQL support
  • Cloudflare Worker backend with D1 storage and the same API contract
  • Token-to-user mapping for small teams or hosted deployments
  • Python adapter and CLI wrapper for generic command monitoring
  • macOS menu bar viewer and Tauri-wrapped dashboard surface

Architecture

flowchart LR
  subgraph Local
    Codex["Codex hook"]
    Claude["Claude Code hook"]
    Daemon["Runlight local daemon<br/>127.0.0.1:18767"]
    LocalServer["Embedded local server<br/>127.0.0.1:18765"]
    LocalDashboard["Embedded dashboard<br/>127.0.0.1:18766"]
    Python["Python / CLI adapter"]
    Custom["Custom adapter"]
  end

  subgraph Servers
    FastAPI["FastAPI server<br/>SQLite or PostgreSQL"]
    Worker["Cloudflare Worker<br/>D1"]
  end

  subgraph Viewers
    Dashboard["React dashboard<br/>Browser or Tauri"]
    Menubar["macOS menu bar"]
  end

  Codex -->|"runlight hook codex"| Daemon
  Claude -->|"runlight hook claude"| Daemon
  Daemon -->|"local mode"| LocalServer
  LocalDashboard --> LocalServer
  Daemon -->|"POST /api/events"| Servers
  Python -->|"POST /api/events"| Servers
  Custom -->|"POST /api/events"| Servers
  Viewers -->|"GET /api/sessions/*"| Servers

Codex and Claude hooks never upload directly to the hosted server. They hand raw hook payloads to the local daemon, which maps them to Runlight protocol events, adds local metadata such as Codex titles, pinned state, and automation hints, stores them in ~/.runlight/queue, and uploads them with the user's dashboard-generated upload token. The same server and viewer contract works against both server implementations. See docs/architecture.md for the detailed component model and deployment boundaries.

Repository Layout

PathPurpose
server/Self-hosted FastAPI API server
workers/Cloudflare Workers + D1 API-compatible server
dashboard/React dashboard and Tauri desktop wrapper
menubar/Swift macOS menu bar viewer
bin/ and src/local/npm runlight CLI, local daemon, queue, settings, and hook adapters
adapters/codex-hook/Compatibility installer and shim for Codex hooks
adapters/claude-code-hook/Compatibility installer and shim for Claude Code hooks
adapters/python/Python client library and runlight CLI
plugins/runlight-codex/Packaged Codex plugin
plugins/runlight-claude/Packaged Claude Code plugin
docs/Architecture and deployment notes

Quick Start

For the hosted Cloudflare deployment, the normal user path is the npm CLI plus a dashboard-generated upload token. You need Node.js 20+ and npm.

1. Install the local CLI

npm install -g runlight

From a source checkout, use:

npm install -g .

2. Set up this machine

runlight setup

The setup flow asks which mode you want:

  • Runlight Cloud opens a browser login page, signs you in, returns the upload credential to the CLI automatically, starts the daemon, and installs Codex and Claude hooks.
  • Local only starts an embedded local server, dashboard, and daemon on this machine. It does not require an account or a visible token.
  • Self-hosted lets this machine run the server, act as a client for another server, or do both. Client machines only need the server address.

Non-interactive setup is also available:

runlight setup --cloud
runlight setup --local
runlight setup --self-hosted --role server
runlight setup --self-hosted --role client --server 192.168.1.20:18765
runlight setup --self-hosted --role both

Codex will ask you to review the new hooks the next time you start a Codex session. Choose Trust all and continue once; after that Runlight runs in the background.

3. Verify local setup

runlight status

Start a fresh Codex or Claude Code session after installing hooks, then watch it appear in the dashboard.

For advanced/manual setup, open /connect on your Runlight server without a CLI handoff code, copy the token shown there, then use runlight login, runlight daemon start, and runlight plugin <codex|claude>.

To disconnect this machine from Runlight:

runlight logout

Logout removes the local upload token, uninstalls Codex and Claude hooks, and stops the local daemon. Run runlight setup again to reconnect.

Local Development Server

runlight setup --local is the normal local-only path. To run the FastAPI server and React dashboard from source for development:

cd server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m uvicorn runlight.app:app --host 127.0.0.1 --port 8766

cd ../dashboard
npm install
npm run dev -- --host 127.0.0.1 --port 3000

Point the daemon at the source server with runlight setting or runlight login --server http://127.0.0.1:8766 --token <token>.

Agent Integrations

Codex

Install Codex hooks through the npm CLI:

runlight plugin codex

The installer writes user-level hook configuration to $CODEX_HOME/hooks.json or ~/.codex/hooks.json and enables Codex's local hook feature in $CODEX_HOME/config.toml or ~/.codex/config.toml. The hook command is runlight hook codex, so Codex only talks to the local daemon.

The packaged Codex plugin is still useful for skill/marketplace workflows:

codex plugin marketplace add /path/to/Runlight
codex plugin add runlight@runlight-local

RUNLIGHT_PLUGIN_DIR="$(ls -td ~/.codex/plugins/cache/runlight-local/runlight/* | head -1)"
bash "$RUNLIGHT_PLUGIN_DIR/skills/runlight/scripts/install-codex-hook.sh"

The local daemon adds Codex session title and pinned-thread state when those local Codex state files are available.

Claude Code

Install Claude Code hooks through the npm CLI:

runlight plugin claude

The installer writes user-level hook configuration to ~/.claude/settings.json unless CLAUDE_SETTINGS_FILE is set. The hook command is runlight hook claude, so Claude Code only talks to the local daemon.

The packaged plugin remains available:

cd plugins/runlight-claude
bash install.sh

The Claude Code integration records session lifecycle, tool activity, permission requests, prompts, subagent starts and stops, and terminal events.

Python and Generic CLI

Install the Python adapter:

cd adapters/python
pip install -e ".[dev]"

Wrap a command:

runlight-adapter run --agent generic -- python -m pytest

Send manual lifecycle events:

runlight-adapter event --session demo-1 --type user_input.waiting --summary "Waiting for review"
runlight-adapter heartbeat --session demo-1
runlight-adapter finish --session demo-1 --result completed --summary "Done"

Configure the adapter with environment variables:

export RUNLIGHT_SERVER_URL=http://127.0.0.1:18765
export RUNLIGHT_TOKEN=

Deployment

Local or LAN Self-Hosting

The npm CLI can run an embedded server and dashboard without Python:

runlight setup --local
runlight setup --self-hosted --role server
runlight setup --self-hosted --role client --server <server-host>:18765
runlight setup --self-hosted --role both

The embedded server stores local data under ~/.runlight/local-server.json and accepts empty credentials as the default user. If clients provide bearer tokens, the same token maps to the same hashed local user id.

The FastAPI server is still available for Python/PostgreSQL deployments. It uses SQLite by default:

cd server
python -m uvicorn runlight.app:app --host 127.0.0.1 --port 8766

For FastAPI LAN access or multi-user testing, bind to all interfaces and set a token map:

RUNLIGHT_TOKEN_MAP='tok-alice:alice,tok-bob:bob' \
python -m uvicorn runlight.app:app --host 0.0.0.0 --port 8766

FastAPI clients and viewers then use the same connection shape:

{
  "server_url": "http://<server-host>:8766",
  "token": "tok-alice"
}

For PostgreSQL, set:

export RUNLIGHT_DATABASE_URL='postgresql+asyncpg://runlight:<password>@<host>:5432/runlight'

Cloudflare Workers and D1

The Worker backend is API-compatible with the FastAPI server.

cd workers
npm install
npm run verify
npm run db:create

Copy the generated D1 database id into workers/wrangler.toml, then run:

npx wrangler d1 migrations apply runlight-db --remote
npx wrangler secret put PUBLIC_BASE_URL
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npm run deploy

The hosted dashboard uses GitHub or Google OAuth sessions. runlight setup opens /connect?cli_code=..., signs the user in, and returns a short-lived upload token to the CLI automatically. Set PUBLIC_BASE_URL to the dashboard origin, for example https://runlight.renaissancemind.ai. OAuth callbacks are /auth/callback/github and /auth/callback/google. RUNLIGHT_TOKEN_MAP remains available for static small-team deployments, but generated dashboard tokens are the normal hosted flow. See workers/README.md for the full Cloudflare flow.

API Contract

All clients and viewers use the same REST API:

MethodPathPurpose
POST/api/eventsIngest one event or { "events": [...] } batch
GET/api/healthHealth check
GET/api/ingest/healthBearer-token ingest credential check
GET/api/users/currentResolve current user from bearer token
GET/api/sessions/liveList active, pinned, or still-visible sessions
GET/api/sessionsList sessions with optional filters
GET/api/sessions/:idFetch one session
GET/api/sessions/:id/eventsFetch a session timeline
GET/api/events/recentFetch recent completion events
DELETE/api/sessions/:idDelete one session and its events
GET/api/tokensList upload token previews for the signed-in user
POST/api/tokensGenerate an upload token for agent hooks
DELETE/api/tokens/:idDelete one upload token
GET/api/user-settingsRead the signed-in user's theme and language defaults
PATCH/api/user-settingsSave the signed-in user's theme and language defaults
POST/api/connect/cliBrowser side of automatic CLI setup handoff
GET/api/connect/cli/:codeCLI side of automatic setup token handoff

Single-event ingest example:

curl -X POST http://127.0.0.1:18765/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "demo-1",
    "agent_type": "generic",
    "adapter_name": "curl",
    "event_type": "session.started",
    "event_time": "2026-06-10T00:00:00Z",
    "summary": "Manual smoke test"
  }'

Standard event types include session.started, session.heartbeat, tool.started, tool.finished, command.started, command.finished, permission.requested, user_input.waiting, external.waiting, session.completed, session.failed, and session.aborted.

Configuration

Server environment variables use the RUNLIGHT_ prefix.

Local CLI configuration lives in ~/.runlight/config.json unless RUNLIGHT_HOME is set. Defaults are 127.0.0.1:18765 for the embedded local server, 127.0.0.1:18766 for the embedded dashboard, and 127.0.0.1:18767 for the local daemon. The daemon stores queued hook events under ~/.runlight/queue and uploads them to the configured server.

Useful local commands:

runlight setup
runlight login
runlight logout
runlight setting
runlight status
runlight health
runlight daemon start
runlight server start
runlight dashboard start
runlight plugin codex
runlight plugin claude
VariableDefaultDescription
RUNLIGHT_SERVER_HOST127.0.0.1Host used by server settings
RUNLIGHT_SERVER_PORT8766Port used by server settings
RUNLIGHT_DATABASE_URLsqlite+aiosqlite:///runlight.dbSQLAlchemy database URL
RUNLIGHT_TOKEN_MAPemptyComma-separated token:user_id map
RUNLIGHT_ALLOWED_TOKENSemptyTokens mapped to the default user
RUNLIGHT_HEARTBEAT_STALE_SECONDS120Gap before a live session is marked stale
RUNLIGHT_EVENT_RETENTION_DAYS30Event retention setting
RUNLIGHT_SESSION_RETENTION_DAYS90Session retention setting
RUNLIGHT_CORS_ORIGINS*Comma-separated allowed origins
RUNLIGHT_MAX_PAYLOAD_BYTES65536Maximum accepted payload size
RUNLIGHT_REQUIRE_AUTHunsetWorker-only browser/API mode; set to true to require OAuth session or bearer token

The server and adapters still accept the previous AGENT_MONITOR_* names as compatibility fallbacks, but new deployments should use RUNLIGHT_*.

An empty or missing bearer token maps to the default user. Once a token map is configured, unknown bearer tokens are rejected.

Development

Run checks for the component you changed.

Local npm CLI and daemon

npm test

Server

cd server
pip install -e ".[dev]"
pytest

Dashboard

cd dashboard
npm install
npm test
npm run build

Run the Tauri desktop shell:

cd dashboard
npm run tauri dev

Workers

cd workers
npm install
npm run verify

Python adapter

cd adapters/python
pip install -e ".[dev]"
pytest

macOS menu bar viewer

cd menubar
swift run RunlightBar

Documentation

Known Boundaries

  • Hook installers modify user-level Codex or Claude Code configuration.
  • Codex plugin installation alone does not activate monitoring; run runlight plugin codex or the bundled hook installer after plugin install or update.
  • Codex and Claude hooks are fail-open and only call the local daemon. The daemon owns token storage, event enrichment, queueing, retry, and upload.
  • Do not expose the self-hosted server to untrusted networks without TLS and an explicit auth boundary.
  • No license file is currently present in this repository.

Contributing

Focused issues and pull requests are welcome. For changes that affect the event protocol, API contract, hook installers, or status inference, include tests for the touched component and update the relevant documentation.

License

No license has been declared yet. Add a LICENSE file before distributing or accepting external contributions under an open-source license.

Ver o original no GitHub

Bom para

Relacionados