AI coding session orchestrator — persistent sessions, multi-engine management, methodology enforcement, mobile access
claude code · codex · gemini cli · aider · openclaw · tmux · pwa · zero dependencies
macOS only (launchd required for service management)
You VPN into your dev machine. You SSH in. You navigate to your project directory, fire up an AI coding agent, and start building. Thirty minutes later your VPN hiccups, or your SSH tunnel drops, or your laptop goes to sleep — and the session is gone. The agent's context, your conversation history, everything. There's no way to reconnect. You SSH back in, start over, and re-explain what you were doing.
TangleClaw was built to fix that. It wraps AI coding sessions in persistent tmux processes so they survive network drops, device switches, and reconnects. Close your laptop at your desk, open your phone on the couch, and pick up the exact same session. The agent never knows you left.
What started as session persistence grew into a full orchestration platform. Once you have persistent sessions, you start wanting a dashboard to manage them. Then you want your development methodology enforced as structural rules, not suggestions the agent can ignore. Then you want engine-native config generated automatically so Claude Code, Codex, Gemini CLI, and Aider all get the same instructions without you maintaining four different config files. Then you want port conflict management across projects, mobile access, idle detection, session wrap protocols.
TangleClaw is all of that — a local platform that sits between you and your AI coding agents, accessible from any browser or phone on your network.
Dashboard — project cards with engine badges, methodology status, git info, and session indicators
Project detail panel — engine, methodology, active session, git state, settings, and session management
PortHub registry — all port leases grouped by project with conflict detection
- Persistent sessions — AI engine sessions run in tmux, surviving network drops, device switches, and reconnects. Close your laptop, switch devices, pick up where you left off
- Five built-in engines — Claude Code, Codex, Gemini CLI, Aider, and OpenClaw. Write rules once — TangleClaw generates engine-native config so every agent gets the same instructions
- Methodology enforcement — pluggable JSON templates define phases, rules, and session behavior. Rules are structural gates, not suggestions. First-class Prawduct integration for governed workflows with independent Critic review
- PortHub built in — central port registry preventing conflicts across all projects. Originally a standalone CLI, now fully integrated into TangleClaw with permanent and TTL leases, heartbeat support, and system-wide conflict detection via lsof
- Dashboard & mobile PWA — manage projects, launch sessions, and interact with AI agents from any browser or phone on your network. Installable on iOS and Android
- OpenClaw integration — connect to remote OpenClaw instances via SSH or Web UI mode with automatic SSH tunnel management, and live background process visibility via ClawBridge
- Zero dependencies — Node.js 22+ stdlib only. No npm install, no build step, no bundler
All features
- Session briefings — auto-generated context from methodology state, active learnings, and last session summary, injected on session start
- Structured session wrap — configurable close-out with version bumps, changelog updates, learnings capture, and next-session priming
- Command bar — inject commands into running sessions without touching the terminal. Quick command pills for common operations and engine-specific slash commands
- Peek — slide-up drawer showing the last lines of terminal output — check progress without scrolling
- File upload — send files into the project directory from the session wrapper (images, docs, configs up to 15 MB)
- Idle chime — audio notification when the terminal goes idle, so you know the agent has finished
- Session history — start time, duration, engine, wrap status, and wrap summary per project
- Engine-native config generation — CLAUDE.md, .codex.yaml, GEMINI.md, .aider.conf.yml generated automatically from your rules
- Custom engines — adding a new engine is a single JSON profile, no code changes
- Model status monitoring — live upstream API status for Claude (Anthropic), Codex (OpenAI), and Gemini (Google) in the session banner
- Prawduct integration — discovery, planning, building phases with independent Critic review and continuous learning. Installed separately; TangleClaw auto-detects and integrates
- Custom methodologies — create your own templates with custom phases, rules, actions, and hooks
- Global rules — markdown rules applied to every project across all engines, editable from the dashboard
- Methodology switching — switch methodologies on any project with automatic state archival and rollback support
- Project management — create, attach, filter, tag, and delete projects from a central landing page
- Setup wizard — first-run guided setup scans for existing projects, detects engines, configures preferences
- Project groups & shared documents — group related projects, share markdown documents across groups with document locking
- PortHub — central port registry preventing conflicts across all projects. Permanent and TTL leases with heartbeat support
- HTTPS/TLS — optional TLS via mkcert for secure remote access
- OpenClaw — SSH or Web UI mode, connection registry, health checks, auto SSH tunnels, reverse proxy, auto device pairing
- ClawBridge — live background process visibility — status pills, detail panels with timestamps, exit codes, attention flags
- Eval Audit Mode — multi-tiered AI agent evaluation. Ingests exchange data from OpenClaw, scores with intelligent gating, tracks baselines, detects drift, generates incidents
- 62 API endpoints — full REST API for everything TangleClaw does
- 1,314 tests — comprehensive test suite using node:test
- SQLite storage — runtime state in a single database file, JSON config for settings
- macOS — TangleClaw uses launchd for service management. Linux support is not yet available
- Node.js 22+ — required for
node:sqliteandnode:test - ttyd — browser-based terminal access (
brew install ttyd) - tmux — session multiplexer (
brew install tmux) - At least one AI CLI engine — Claude Code, Codex, Gemini CLI, or Aider
- Prawduct (optional) — install separately for governed workflows with discovery, planning, building phases, and independent Critic review
- OpenClaw (optional) — for remote AI agent sessions. Requires SSH access to the OpenClaw host
- ClawBridge (optional) — for background process visibility on OpenClaw instances
git clone https://github.com/Jason-Vaughan/TangleClaw.git
cd TangleClaw
./deploy/install.shThe install script:
- Checks prerequisites (node 22+, ttyd, tmux)
- Generates launchd plists with correct paths
- Installs and loads the services
- Runs a health check
Access the landing page at http://localhost:3102. On first launch, a setup wizard walks you through configuration — including choosing your projects directory. This is a single folder where all your managed projects live (e.g., ~/Projects). TangleClaw scans this directory, detects existing repos and engines, and lets you attach them as managed projects.
TangleClaw runs an HTTP or HTTPS server with browser-based terminal access. HTTPS is supported via mkcert or any TLS certificate — enable it in config with httpsEnabled, httpsCertPath, and httpsKeyPath. There is no user authentication on the server itself — anyone who can reach the port can view your projects and open terminal sessions. The deletePassword config option protects destructive operations (project deletion, data reset) but does not gate general access.
Recommendations:
- Enable HTTPS for any non-localhost access (required for OpenClaw Web UI device pairing)
- Run TangleClaw on a trusted network or behind a VPN (e.g., Tailscale, WireGuard)
- Do not expose TangleClaw ports to the public internet
- If accessing from mobile over Wi-Fi, ensure your network is private
- User Guide — Getting started, UI walkthrough, mobile setup, troubleshooting
- Methodology Guide — Built-in templates, creating custom methodologies, rules
- Engine Guide — Built-in engines, creating custom engine profiles
- Configuration Reference — All config fields, JSON schemas, API overview
- OpenClaw Setup — Connecting to remote OpenClaw instances, SSH tunnels, Web UI mode, HTTPS
- Eval Audit Mode — AI agent evaluation pipeline, scoring, baselines, drift detection
Global config lives at ~/.tangleclaw/config.json (auto-created on first run).
Key settings:
serverPort— Landing page server port (code default: 3101, launchd override: 3102)ttydPort— ttyd terminal port (code default: 3100, launchd override: 3101)projectsDir— Root directory for managed projectsdefaultEngine— Default AI engine for new projectsdefaultMethodology— Default methodology templatedeletePassword— Optional password for destructive operationshttpsEnabled/httpsCertPath/httpsKeyPath— TLS configuration
Engine profiles: ~/.tangleclaw/engines/*.json
Methodology templates: ~/.tangleclaw/templates/
See the Configuration Reference for all fields, types, and defaults.
node --test 'test/*.test.js'launchd (com.tangleclaw.server)
└─ node server.js
├─ Landing page HTTP server (:3102)
├─ API endpoints (/api/*)
├─ Reverse proxy /terminal/* → ttyd (:3101)
├─ Reverse proxy /openclaw/* → SSH tunnel → OpenClaw gateway
├─ WebSocket upgrade (ttyd + OpenClaw)
└─ Session wrapper + OpenClaw viewer HTML serving
launchd (com.tangleclaw.ttyd)
└─ ttyd --port 3101 tmux attach
└─ WebSocket terminal access
tmux sessions (spawned on demand)
└─ One per active project session
└─ AI engine process (claude, codex, gemini, aider)
SSH tunnels (spawned on demand)
└─ One per active OpenClaw connection
├─ Gateway port forward (18789)
└─ ClawBridge port forward (3201, sidecar)
Project Structure
server.js # HTTP server, API routes, reverse proxy, WebSocket upgrade
lib/
store.js # Storage abstraction (JSON config + SQLite runtime)
logger.js # Structured logging with rotation
tmux.js # tmux session management
git.js # Git operations
system.js # System resource stats
engines.js # Engine profile loading, detection, config generation
methodologies.js # Methodology templates, init, switching, status
projects.js # Project CRUD, enrichment, auto-detection
sessions.js # Session lifecycle (launch, prime, wrap, kill)
skills.js # Skills system (session-wrap skill)
porthub.js # PortHub integration (port registration)
port-scanner.js # Periodic system port conflict detection
uploads.js # File upload handling for AI sessions
tunnel.js # SSH tunnel manager for OpenClaw connections
sidecar.js # Background process visibility (ClawBridge polling)
model-status.js # Upstream API status monitoring
eval-audit.js # AI agent evaluation pipeline
update-checker.js # Version update checks
pidfile.js # PID file management
public/
index.html # Landing page
session.html # Session wrapper page
openclaw-view.html # OpenClaw direct-connect viewer
style.css # Landing page styles
session.css # Session wrapper styles
landing.js # Landing page logic
ui.js # Landing page UI rendering
session.js # Session wrapper logic
openclaw-view.js # OpenClaw viewer logic (sidecar pills, detail panel)
setup.js # First-run setup wizard
manifest.json # PWA manifest
sw.js # Service worker
data/
engines/ # Bundled engine profiles (claude, codex, gemini, aider, genesis, openclaw)
templates/ # Bundled methodology templates
test/ # Test files (node:test, 1314 tests)
deploy/ # launchd plists and install script
hooks/ # Git hooks (reference, not auto-installed)
docs/ # User documentation
Reference hooks are provided in hooks/. To install:
cp hooks/pre-commit .git/hooks/pre-commit
cp hooks/commit-msg .git/hooks/commit-msg
cp hooks/post-commit .git/hooks/post-commit
chmod +x .git/hooks/pre-commit .git/hooks/commit-msg .git/hooks/post-commit- pre-commit: Runs the full test suite
- commit-msg: Validates first line is non-empty and ≤72 characters
- post-commit: Tags the version from
version.jsonon the main branch
# Restart server (launchd auto-restarts via KeepAlive)
launchctl kill SIGTERM gui/$(id -u)/com.tangleclaw.server
# Stop services
launchctl unload ~/Library/LaunchAgents/com.tangleclaw.server.plist
launchctl unload ~/Library/LaunchAgents/com.tangleclaw.ttyd.plist
# View logs
tail -f ~/.tangleclaw/logs/tangleclaw.log
# Health check
curl -s http://localhost:3102/api/health | python3 -m json.toolPlanned features and improvements — contributions and feedback welcome.
- TangleMeth — AI-guided methodology builder. Instead of hand-writing template JSON, TangleMeth interviews you about your governance needs and generates a complete methodology framework: phase docs, enforcement hooks, artifact templates, and test suites. Compose from existing methodologies or fork and modify them
- Multi-engine sessions — Launch multiple engines on the same project simultaneously (e.g., Claude Code for implementation, Codex for review)
- Sidecar controls — Poll/refresh individual processes, show full output, dismiss, terminate from the detail panel
- Linux support — systemd service management as an alternative to launchd
- Mobile terminal scrollback — Improved touch scroll handling for xterm.js on iOS and Android
MIT — see LICENSE.