convez.ai
AgenteAutomaçãoIntermediário
teriansilva

Agent Sessions

teriansilva/agent-sessions

Central de comando para agentes de IA com terminal persistente

Ver no GitHub
InicialPluginScore · de 0 a 100

Dashboard mobile-first auto-hospedado que centraliza sessões de agentes de IA (Claude Code, Codex, opencode, Gemini) com terminal persistente integrado. Oferece histórico renderizado, controle de sessões e reativação após reboots — tudo acessível via web ou mobile.

Instalação

$npx convez-ai teriansilva/agent-sessions

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
2
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 1 dia
Versão
v0.19.4
Issues abertas
1
Contribuidores
1

Casos de uso

  • Gerenciar múltiplos agentes de IA em um único painel
  • Manter sessões de terminal ativas entre reboots e deploys
  • Controlar agentes de codificação (Claude, Codex, Gemini) remotamente
  • Revisar histórico de conversas e execuções em markdown limpo

Veredito

Ferramenta sólida para quem trabalha com múltiplos agentes de IA e precisa de persistência terminal real. Instalação simples (rootless), mas exige proxy reverso com TLS/autenticação — não é plug-and-play. Recomendado para desenvolvedores que querem controle centralizado sem dependências de sistema.

README

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

agent-sessions (BattleLab)

A mobile-first, self-hosted command deck for your AI-coding agents. One web app that organizes every session from Claude Code, Codex, opencode, and Gemini, with a real terminal that survives reboots and deploys — drive your whole fleet from a laptop or a phone.

"Command & Code" · battlelab.superstatus.io

license: MIT self-hosted engines

Why

  • Every agent, one place. A live sidebar of all your sessions across four engines, grouped by project, newest-first, with per-row engine badges + filtering.
  • Persistent terminals. Each session runs under its own detached PTY (dtach) — reattach after a tab close, reboot, or app upgrade and the conversation is right where you left it.
  • Console-style scroll-up. Scroll back into clean, rendered history (markdown + ● turn markers) for all four engines — not a width-fragile byte replay.
  • Start new sessions for Claude, Codex, and opencode straight from the picker.
  • Mobile-first. A touch-ready terminal with a real compose bar, control keys, and image paste.
  • One-line, rootless install. No root, no system daemon; atomic releases with one-step rollback and an opt-in self-updater.
curl -fsSL https://battlelab.superstatus.io/install.sh | sh

Single-admin tool — it launches agents with permission bypass by design. Run it on your own host, behind a reverse proxy (TLS + auth). See Security / trust model.


A React + Vite SPA. Sidebar: every session from each installed engine — Claude Code (~/.claude/projects/**/*.jsonl), opencode (SQLite at ~/.local/share/opencode/opencode.db, read-only), codex, and gemini — grouped by project, sticky-first then by recency, with a per-row engine badge + agent filter. The open session lives in the URL (/s/:engine/:id); clicking a row attaches to it. The embedded terminal is self-owned — xterm.js over a websocket (/ws/term/{sid}) bridged to a per-session dtach PTY that resumes the engine in the right cwd (claude --resume <uuid> / opencode <dir> --session <ses_id> / …). No ttyd, no Zellij.

Engines live behind a small provider interface (engines.py); identity is engine-qualified <engine>:<native_id> (e.g. claude:<uuid>, opencode:<ses_id>). opencode is read-only with respect to its own DB — the sidebar never writes opencode.db. Archive is refused for opencode ids (our archive physically moves the Claude JSONL, which opencode has no equivalent for); the title/sticky sidecar overlay still works for any engine, since that's our metadata.json, not opencode's data. Adding an engine = one new provider in the registry.

Install & operate

Rootless, user-level — no system daemon, no root. The installer drops everything under ~/.local/share/agent-sessions/, runs the app as a systemctl --user service, and binds 127.0.0.1:8765 (put a reverse proxy / TLS in front yourself — it does not configure nginx).

# Read the script first if you like — it's plain POSIX sh.
curl -fsSL https://battlelab.superstatus.io/install.sh | sh

A worked reverse-proxy example lives in deploy/nginx.example.conf; a full self-host walkthrough is in INSTALL.md. To install from a fork/mirror, set AGENT_SESSIONS_REPO=https://github.com/<you>/agent-sessions.git before running the script.

Prereqs: git and python3 ≥ 3.11. If the venv module is missing the installer offers to apt-get/dnf install it (the only sudo step, and it's prompted). On a fresh install it prints the generated admin credentials once:

agent-sessions 0.3.1 installed.
  URL:      http://127.0.0.1:8765
  username: admin
  password: <generated>            ← shown once; only the PBKDF2 hash is stored

First login forces a password change before anything else is reachable. Lost it? Reset from the host (never pass the password on the command line — it leaks via shell history/ps):

~/.local/share/agent-sessions/current/venv/bin/agent-sessions reset-password --prompt   # interactive, no echo
… reset-password --stdin    # scriptable: read one line from stdin
… reset-password            # generate a random one and print it once

Optional two-factor auth (TOTP). Off by default. Enable it from Settings → Two-factor authentication: scan the QR (or enter the key) into an authenticator app (Google Authenticator, Authy, 1Password, Aegis…), confirm a code, and save the one-time recovery codes shown once. After that, login asks for a 6-digit code after your password. The TOTP secret + recovery-code hashes live in a 0600 file next to the env (<env-dir>/2fa.json, override AGENT_SESSIONS_2FA_FILE) — never in prefs.json or the metadata sidecar. Locked out (lost device and recovery codes)? Clear 2FA from the host:

~/.local/share/agent-sessions/current/venv/bin/agent-sessions clear-2fa    # removes the 2FA secrets file → 2FA off

What the installer creates

~/.local/share/agent-sessions/
├── releases/<ts>-<sha>/{src,venv}   one self-contained release per build
├── current → releases/<ts>-<sha>     atomic symlink (rename(2)); flip = upgrade/rollback
└── env                               0600; secret + admin hash + host/port/origin
~/.config/systemd/user/agent-sessions.service

Re-running the installer is idempotent: it builds a new release dir, flips current, keeps the prior releases (3 by default) for rollback, and leaves existing credentials untouched. It also runs agent-sessions doctor each time to (re)discover installed agent CLIs (claude/codex/opencode/gemini) and record their paths in env.

Install-time knobs (env vars): AGENT_SESSIONS_CHANNEL (stable tags — default — or main), AGENT_SESSIONS_HOST/_PORT/_ORIGIN, AGENT_SESSIONS_HOME, AGENT_SESSIONS_REF (pin an exact tag/branch/sha), AGENT_SESSIONS_NO_SERVICE=1 (install without touching systemd).

Updating

Self-update never runs arbitrary input — it only moves to the channel's latest release, flips current, restarts, health-checks /healthz, and rolls back to the prior release if the new one fails.

  • In-app: the dashboard shows the version + a check/apply control (/api/version, /api/update/check, /api/update/apply — authed + CSRF + origin-gated).
  • CLI: agent-sessions autoupdate (check the channel, apply only if newer).
  • Opt-in autoupdate timer: pass AGENT_SESSIONS_AUTOUPDATE=1 at install (optionally AGENT_SESSIONS_AUTOUPDATE_ONCALENDAR=daily) and a agent-sessions-update.timer runs the same guarded apply on a schedule. Default off; re-running the installer without the flag tears the timer back down.

Rollback & emergency-disable

Releases are immutable directories; current is just a symlink, so rollback is a one-step re-point — no rebuild:

P=~/.local/share/agent-sessions
ls -1dt $P/releases/*/                       # newest first; pick the known-good one
# atomic re-point — same temp-link + rename(2) the installer uses, so a concurrent
# start/health-check never sees a missing `current` (bare `ln -sfn` unlinks first):
ln -s $P/releases/<ts>-<sha> $P/.current.rb && mv -Tf $P/.current.rb $P/current
systemctl --user restart agent-sessions.service

(A failed self-/auto-update already rolls back automatically; this is the manual path.)

Emergency-disable — stop serving and/or stop auto-updating:

systemctl --user stop    agent-sessions.service          # take the app down now
systemctl --user disable agent-sessions.service          # …and keep it down across logins
systemctl --user disable --now agent-sessions-update.timer   # stop autoupdate only
journalctl --user -u agent-sessions.service -f           # logs

Security / trust model

agent-sessions is a single-admin tool. Understand this before exposing it:

  • It launches AI-coding agents with permission bypass by design — --dangerously-skip-permissions (Claude Code) / --yolo-equivalent toggles. A logged-in user can run arbitrary commands in any project on the host. Treat the whole surface as equivalent to a shell as the user the service runs as — the same trust boundary as SSH.
  • It is not multi-tenant. There is one admin account; there is no per-user isolation. Do not share a login.
  • The app binds 127.0.0.1 and does not terminate TLS or do rate-limiting itself. You must put it behind a reverse proxy that provides TLS + auth. See deploy/nginx.example.conf.
  • Defence in depth: the app has its own cookie + CSRF + same-origin (Origin/Referer must equal AGENT_SESSIONS_ORIGIN) checks, and /api/auth-check (204/401) so the reverse proxy can additionally gate with auth_request. Rate-limit /login at the proxy to blunt credential stuffing.
  • Optional TOTP 2FA adds a second factor on top of the password (see Install & operate). A correct password issues only a short-lived pre-auth cookie; the full session is minted after a valid authenticator/recovery code. Recommended once the instance is reachable beyond localhost. clear-2fa (host-only) is the lockout escape hatch.

Where things live

  • App code: here (src/agent_sessions/)
  • Deploy unit (ships with the code): deploy/ — agent-sessions.service (the FastAPI app; the installer manages it). The terminal is in-process (the ws bridge), so there's no separate terminal unit.
  • Reverse-proxy example: deploy/nginx.example.conf
  • Self-host guide: INSTALL.md

Layout

agent-sessions/
├── pyproject.toml
├── src/agent_sessions/
│   ├── main.py        thin FastAPI app factory: create_app() builds shared state +
│   │                  middlewares + lifespan, then calls each routes/ registrar
│   ├── routes/        one register(app, *, deps) module per route group —
│   │   ├── system.py      healthz, auth-check, version, engines, system, update, config, prefs
│   │   ├── sessions.py    /api/sessions, /api/projects (entities, #361), /api/folders, rename, archive/unarchive
│   │   ├── scrollback.py  /api/scrollback (+ clear)
│   │   ├── upload.py      /api/upload
│   │   ├── auth.py        login, /login/totp, logout, change-password, /api/password, 2FA
│   │   ├── terminal.py    the /ws/term/{sid} websocket handler
│   │   └── spa.py         GET / + the /{spa_path} SPA catch-all (registered last)
│   ├── scanner.py     read ~/.claude/projects/ (live + archive)
│   ├── metadata.py    sidecar JSON with fcntl.flock; title/sticky/sort_key/project_alias
│   ├── engines/       per-engine providers (scan + launch_argv): base.py (contract +
│   │                  patterns + binaries), claude/opencode/codex/gemini.py, registry.py
│   │                  (parse_key/scan_all/…); __init__ re-exports the public surface
│   ├── webterm.py     the ws↔PTY bridge run loop (xterm.js over /ws/term, dtach-backed)
│   ├── scrollback.py  per-session scrollback ring + on-disk mirror + resume/scroll-up
│   ├── transcript.py  engine-agnostic scroll-up renderer from the saved conversation
│   ├── ptybridge.py   dtach create-or-attach argv + session-exists probe
│   ├── session_stream.py  process-wide SessionRegistry + per-session readers (#183)
│   ├── auth.py        cookie + CSRF + Origin + /api/auth-check for nginx auth_request
│   └── templates/     login.html + login_totp.html + change_password.html (server-rendered pages)
├── web/               React + Vite + TS SPA (built to web/dist, served by main.py)
├── tests/             pytest; subprocess.run stubbed; covers shell-free, CSRF, lock, lookup
├── deploy/
│   ├── agent-sessions.service     systemd-user unit, FastAPI app
│   └── nginx.example.conf         sample reverse-proxy vhost (TLS + ws upgrade)
└── .forgejo/workflows/            CI (lint + tests) + deploy

Running locally

python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

Bring up the app against a fake home (no real Claude sessions touched):

export AGENT_SESSIONS_USERNAME=admin
export AGENT_SESSIONS_PASSWORD_HASH=$(python -c "from agent_sessions.auth import hash_password; print(hash_password('hunter2'))")
export AGENT_SESSIONS_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(48))")
export AGENT_SESSIONS_ORIGIN=http://localhost:3402
uvicorn --app-dir src --host 127.0.0.1 --port 3402 agent_sessions.main:app

AGENT_SESSIONS_AUTH_MODE selects the auth model: single-user (default — the username + password login above) or none (no login at all; the admin session is auto-established so the SPA, CSRF token and Origin checks still work, but you're never prompted for credentials, and username/password-hash aren't required). Use none only when you trust the network — localhost or behind a VPN — since anyone who can reach the port gets in. CSRF + same-origin enforcement stay on in both modes.

See CONTRIBUTING.md for the full dev setup (web build, tests, conventions).

Permission bypass (--dangerously-skip-permissions)

The sidebar's New session modal has a "bypass permissions" toggle that is on by default, and resuming a session also passes --dangerously-skip-permissions. This is deliberate: it skips Claude Code's workspace-trust prompt so a session opens straight into its already-used folder, and skips per-tool permission prompts for new sessions.

This is acceptable only because agent-sessions is a single-admin tool, on the operator's own host, behind a reverse proxy (TLS + auth) and the app's own cookie auth. The toggle lets you turn bypass off per new session. The flag is asserted by the provider launch_argv tests (tests/test_engines.py) so it can't silently change. See the Security / trust model section above.

API surface

  • GET /api/sessions?limit=20&offset=0&archived=0 — flat, newest-first, paginated ({sessions, next_offset, total, facets}). Optional filters: q (case-insensitive title substring; trimmed, empty = no filter), project (exact key), engine (exact; claude / opencode). Filters are applied before limit/offset so total and "load more" describe the filtered set. facets: {projects, engines} are the distinct values over the full archived-scoped set (computed pre-filter) so the sidebar dropdowns list every option, including rows past the first page.
  • GET /api/folders — new-session picker: scanned cwds ∪ validated ~/claude/* (distinct from the session-list facets above)
  • GET/POST/PATCH/DELETE /api/projects — project ENTITIES (#361): {id, name, color, folders, archived, session_count}; session → project assignment via PATCH /api/sessions/{sid}/metadata {project_id}
  • POST /api/sessions/{uuid}/rename {title} — persists to the sidecar
  • POST /api/sessions/{uuid}/archive · /unarchive — move the JSONL between projects/ and projects-archive/
  • GET /api/config — SPA bootstrap (CSRF, new_session_engines, terminal_backend, theme, two_factor_enabled); POST /api/prefs {theme}
  • POST /api/2fa/enroll → {secret, otpauth_uri, recovery_codes} (shown once) · POST /api/2fa/confirm {code} (enable) · POST /api/2fa/disable · POST /api/2fa/recovery-codes (regenerate) — the last two need a fresh proof ({code} or {password}). Login second step: POST /login → pre-auth → POST /login/totp (form field code). N/A under AUTH_MODE=none.
  • WS /ws/term/{sid} — the terminal: attach to (or, with ?new=1&cwd=&bypass=, launch) a session's dtach PTY
  • GET /api/auth-check — 204/401 for nginx auth_request; POST /login · /logout

All state-changing routes require the CSRF token + an Origin/Referer matching AGENT_SESSIONS_ORIGIN.

Conventions

See CONTRIBUTING.md and the full reference in docs/reference.md. Key points:

  • Shell-free engine launchers — providers build argv lists; the ws bridge runs them under dtach. Pinned by tests + a CI grep.
  • Session = URL = socket identity: one {engine}:{id} ⇒ one dtach master ⇒ one writer; attach, never relaunch.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados