termenbox

Imported from termenbox/termenbox (AGENTS.md). Install upstream with npx skills add termenbox/termenbox. Copyright stays with the author.

Termenbox — AGENTS.md

Knowledge Base

This project uses a fact/decision/guardrail/skill knowledge system. See docs/{facts,decisions,guardrails,skills}/ — facts (what's true), decisions (what's committed to and why), guardrails (what must/must not happen), procedures (how to act). Maintained via capture after work sessions; validated via lint on demand; queried via query.

Project Overview

Termenbox — a web-based terminal for managing remote AI coding agents (Codex, Claude Code) from any mobile browser, with Mosh-level session persistence. No native apps. No subscriptions. Self-hosted.

Key Directories

docs/
  facts/           # Descriptive truths (14 facts)
  decisions/       # Axiomatic commitments (12 decisions)
  guardrails/      # Normative rules (8 guardrails)
  skills/          # Procedural knowledge (tags, roles)
  plans/           # Implementation plans
packages/
  server/          # termenbox-server (Rust: WebRTC + WebSocket, tmux, auth)
  agent/           # termenbox-agent (parked; see issue #19)
  core/            # termenbox-core (Rust, shared protocol types)
  client/          # termenbox-client (Svelte 5, xterm.js WebGL)

Quick Commands

# Build everything
cargo build --workspace --release
pnpm -r build

# Test
cargo test --workspace
pnpm -r test

# WASM
cd packages/core && wasm-pack build --target web --release

# Docker
docker build -t termenbox -f docker/Dockerfile .

# Lint knowledge base
# (requires go-getter plugin)
lint

Architecture Summary

• Baseline: hybrid MVP (DECISION-0051); v1-only designs (SSP, SSH auth, WASM) are deferred
• Transport: WebRTC data channel direct to one UDP port, no STUN/TURN/signaling (DECISION-0057); WebSocket fallback
• Directory: signed records (Pages Functions + D1) map server key -> address/fingerprint (DECISION-0056)
• Auth: GitHub OAuth; one owner per server, claimed with a one-time secret (DECISION-0053)
• Sessions: server owns tmux/PTY via a SessionBackend trait (DECISION-0054); reconnect = re-attach
• Client: Svelte 5 + xterm.js WebGL; hosted or self-hosted (DECISION-0052)
• Deployment: Docker image (ghcr.io), one command from the client; 512MB RAM, 1 vCPU (FACT-0001)
• Plan: docs/plans/termenbox-roadmap.md, tracked in GitHub issues

Guardrail Highlights

• No native apps (GUARDRAIL-no-native-apps)
• No paid services (GUARDRAIL-no-paid-services)
• 512MB RAM / 1 vCPU limit (GUARDRAIL-resource-constraints)
• Secrets in memory only, never logged (GUARDRAIL-security-secrets-handling)
• Internal services on 127.0.0.1 only (GUARDRAIL-internal-network-binding)
• Audit logging without secrets (GUARDRAIL-audit-logging-no-secrets)

Minimum Browser Support

• iOS Safari 16.4+ (DECISION-0112; WebSocket baseline, see FACT-0016)
• Chrome Android 111+
• Desktop: Chrome/Firefox/Edge current-2, Safari 16.4+

License

MIT (DECISION-0011)

Guardrails

Generated by go-getter apply from docs/guardrails/; do not edit this section.

Checked by git hooks and CI:

• Branch names must match the project pattern (branch-names-follow-the-pattern)
• Commit subjects must follow Conventional Commits (commit-subjects-are-conventional)
• The instruction file must stay within 150 lines (instruction-file-within-cap)
• Work must not happen on the default branch (no-commits-on-the-default-branch)

Blocked by host hooks where the host supports it:

• Delegations to a role are routed by expected total step cost (delegations-are-routed)
• A step is not done while its verification checks fail (verification-gate-blocks-done)
• Watches start through go-getter watch, --until done for CI runs and long commands (watches-use-the-wrapper)

Advisory:

• No mid-task model, effort or instruction-file change; switches are confirmed (cache-hygiene-rule)
• A change lands as one squashed pull request with green CI (changes-land-as-one-squashed-pull-request)
• Context is compacted at task boundaries (compaction-timing-rule)
• Handoffs must carry a brief, a result and evidence (handoff-has-brief-result-evidence)
• Agents must hand over to a human when blocked, before irreversible actions and on a guardrail denial (human-escalation-rule)
• No more than 3 agents run at once (max-concurrent-agents-rule)
• Noisy work is delegated only when the cost model says the handoff is cheaper (noisy-work-rule)
• Parallel tasks must each use their own worktree (parallel-tasks-use-worktrees)
• Detailed procedures live in skills loaded on demand (procedure-delivery-rule)
• The reviewer must not modify files (reviewer-read-only)
• Writes to the plan tracker follow the project's answer (tracker-writes-follow-the-answer)