NTM (Named Tmux Manager)

NTM is a Go-based command-line tool designed to orchestrate multiple AI coding agents (such as Claude Code, Codex CLI, and Gemini CLI) in parallel within tmux sessions. It acts as a 'cockpit' or orchestration layer, allowing developers to manage agent workloads, monitor status, and coordinate work distribution.

Core Capabilities

• Spawn sessions: Create tmux sessions with specific counts of different agent types.
• List sessions: View all active NTM sessions and their agent counts.
• Monitor status: Use a real-time TUI to see agent states (idle, working, error, waiting for input).
• Robot output: Generate JSON output for programmatic integration with other tools.
• Kill sessions: Terminate a session and all associated agents.
• Dashboard: (Planned) Web-based monitoring.

# Example: Spawn a session with 3 Claude agents and 2 Codex agents
ntm spawn myproject --cc=3 --cod=2

# Example: List active sessions
ntm list

# Example: Monitor real-time status of a project
ntm status myproject

# Example: Get JSON status for programmatic use
ntm --robot-status

# Example: Terminate a session
ntm kill myproject

The NTM project is transitioning from a basic agent spawning and monitoring system to a highly coordinated environment. Current gaps in the system focus on agent communication, file safety, and command efficiency.

Key areas of improvement include:

• Agent Coordination: Moving from manual macro calls to a single-call bootstrap (macro_start_session) and implementing BD messaging for agent-to-agent coordination.
• File Safety: Implementing a File Reservation Lifecycle (reserve/release/force-release) to prevent multiple agents from editing the same file simultaneously.
• Command Efficiency: Utilizing the full range of bv robot modes (specifically -robot-triage) and moving CM from subprocess calls to an HTTP daemon for faster memory queries.
• Safety & Protection: Adding auto-installed hooks for Destructive Cmd Protection (e.g., preventing accidental git checkout -- operations).
• Intelligence: Moving from a passive session monitor to an intelligent Session Coordinator and implementing smart task assignment via bv graph analysis.

HyperSync is a proposed distributed workspace fabric designed for multi-agent AI coding workloads. It provides single-workspace semantics, meaning multiple AI agents (like Claude Code or Codex) running on different machines see an identical, consistent state as if they were all working on a single machine.

Core Architecture

HyperSync uses a leader-authoritative model:

• Leader (Main Machine): Acts as the single source of truth. It maintains an Op Log (with monotonic sequence numbers and Blake3 content-addressed chunks), runs a RaptorQ Encoder for loss-tolerant broadcasting, and uses a Scheduler to manage agent placement.
• Workers: Run a FUSE Mount (ntmfs/) to intercept filesystem operations. A Worker Daemon captures writes and forwards them to the leader, while a RaptorQ Decoder reconstructs log entries from the leader's broadcast.
• Transport: Uses QUIC for NAT-traversal and congestion control.

NTM uses several patterns for state management that can lead to concurrency hazards if not handled carefully:

• Global Mutable State: Many packages use package-level variables (e.g., projectionStore, outputFormat, stateTracker) that are set via setter functions like robot.SetProjectionStore(). This can cause race conditions during concurrent operations, such as multiple HTTP requests attempting to configure different stores simultaneously.
• Exclusive Mutexes: The Store.Transaction uses an exclusive mutex during SQLite operations. This blocks all other reads while a write is in progress, even though SQLite's WAL mode typically allows concurrent reads.
• Event Dropping: Several internal event systems use fixed-size buffers and will silently drop data when full:
  • EventEmitter: 1024-entry buffer.
  • SSE client channels: 100-entry buffer.
  • WebSocket hub broadcast channel: 256-entry buffer.

When building extensions, prefer passing explicit context objects (like a RobotContext containing store, feed, and config) rather than relying on package-level globals.

The Robot Projection Section Model defines the canonical data structures used to represent the state of the NTM system across various surfaces (like snapshot, status, dashboard, etc.). The model is organized into several key sections, each owned by a specific adapter or service.

Key sections include:

• Summary: High-level counts for quick assessment (e.g., total_sessions, agents_busy, open_alerts).
• Sessions: Detailed state of tmux sessions, windows, and agents.
• Work: Bead state for task management (Ready, Blocked, In Progress).
• Coordination: Agent Mail state, including inboxes, file leases, and active threads.
• Quota: Resource usage for providers (Anthropic, OpenAI, etc.), RCH, and system resources.
• Alerts & Incidents: Active alerts and durable escalations.
• Attention: Prioritized items requiring action.
• Source Health: Metadata indicating the freshness and availability of each section's data.

When a section's source is unavailable, it must include degraded markers: _degraded, _degraded_reason, and _degraded_since, with data fields set to null.