NeuralLoom: Unified AI Agent Orchestrator & Context Bridge

NeuralLoom is a local Next.js orchestration cockpit and terminal bridge designed to manage multiple concurrent terminal agent sessions (such as Claude Code and Aider) in isolated or overlapping workspaces. It streams pseudo-terminal (PTY) streams to the browser over secure WebSockets, manages system prompt environments, compiles directory maps, tracks active token costs, and displays visual resource telemetry.

[!TIP] UI Capabilities & Gap Audit: You can view the live interactive UI Capabilities & Gap Audit Dashboard (or access it locally at /ui-audit.html on the server) to explore current layout components, read-only diff viewers, and the built-in database/terminal consoles.

🚀 Key Features

• Multi-Session Workspace Switcher: Swap between separate active workspaces via a top tab bar. The file explorer tree, git diff panel, terminal stream, and active files are cached independently per session so you never lose your context when swapping projects.
• Split Terminal Console: Split the terminal view horizontally (50/50) to monitor and interact with two different agent sessions simultaneously.
• Resource & Token Analytics:
  • Real-time CPU and Memory telemetry (via docker stats for container runners or process-RSS for local host PTYs).
  • Regex-based PTY stdout parsing to extract input/output tokens and estimated dollar cost metrics on the fly.
• Context Hub & Command Injection:
  • Write shared prompts (cprompt.md) and global guidelines (AGENTS.md).
  • Stage context and directories maps to instantly inject standard commands (like /ccc and /ccp) with one click.
• Inline Git Diff Viewer: Scan changes via git status --porcelain and view modified files with line-by-line syntax-highlighted diffs in a virtual read-only editor tab.
• Flexible Runtimes: Launch sessions in three different environments:
  1. Local Host OS (via Git Bash pseudo-terminals).
  2. Docker Containers (isolated alpine nodes mounting local folders).
  3. Remote VMs (interactive SSH sessions).

🛠️ Architecture & Deployment Model

[!IMPORTANT] NeuralLoom is a local/self-hosted orchestrator and cannot be deployed to serverless environments (like Vercel). It depends on a persistent server runtime to manage active node-pty terminal threads, keep sockets connected, write to the local filesystem, and interface with Docker/SSH.

Core Components

1. Next.js Frontend (Port 9600): Visual IDE layout containing the file explorer, Monaco-style editor textareas, resource telemetry gauges, and xterm.js terminals.
2. Next.js Backend API routes: Filesystem operations, git diff generator, context compilers, and launcher configurations.
3. WebSocket Server Gateway (Port 9601): Intercepts raw keystrokes from the browser, pipes them to respective PTY child processes on the server, and routes stdout buffers back to the UI terminal wrapper.

🔒 Network access & security

[!IMPORTANT] As of v0.3.0, NeuralLoom binds to localhost (127.0.0.1) only by default. Because the dashboard exposes shell, filesystem and database access, it is not reachable from other machines on your network unless you explicitly opt in. Requests whose Host/Origin are not loopback are also rejected (defending against cross-site and DNS-rebinding attacks).

To expose NeuralLoom on your local network, set one of these environment variables before launching:

| Variable | Default | Effect | |---|---|---| | NEURAL_LOOM_ALLOW_LAN | (unset) | Set to 1/true/yes to bind 0.0.0.0 and accept LAN requests. Cross-site Origins are still rejected. | | NEURAL_LOOM_HOST | (unset) | Explicit bind interface (e.g. 0.0.0.0 or a specific IP); overrides the default. | | PORT / WS_PORT | 9600 / 9601 | Override the dashboard and WebSocket gateway ports. |

# Example: allow access from other devices on the LAN
NEURAL_LOOM_ALLOW_LAN=1 npx neural-loom

⚙️ Environment variables

Full reference for every variable NeuralLoom reads:

| Variable | Default | Purpose | |---|---|---| | PORT | 9600 | Dashboard (Next.js) HTTP port. | | WS_PORT | 9601 | WebSocket gateway port. Auto-increments up to +10 on conflict. | | NEURAL_LOOM_ALLOW_LAN | (unset) | Set 1/true/yes to bind 0.0.0.0 and accept LAN requests (cross-site origins still rejected). | | NEURAL_LOOM_HOST | (unset) | Explicit bind interface (e.g. 0.0.0.0 or a specific IP); overrides the default. | | NEURAL_LOOM_MAX_SESSIONS | 25 | Cap on concurrently live sessions, guarding against runaway PTY spawning. 0 disables the cap. | | NEURAL_LOOM_BASH_PATH | (unset) | Windows only: explicit path to bash.exe when Git Bash is installed in a nonstandard location. | | ORIGINAL_CWD | (set by the CLI) | The user's actual workspace directory. The published CLI chdirs to the package root, then exports this so filesystem logic targets your project, not the install dir. Rarely set by hand. |

🗄️ Database drivers (optional)

The SQL explorer's database drivers are optional — NeuralLoom ships without any of them, so an install that never touches SQL stays lean. Install only the driver(s) for the engines you use:

| Engine | Install | |---|---| | PostgreSQL | npm install pg | | MySQL / MariaDB | npm install mysql2 | | SQLite | npm install better-sqlite3 | | Microsoft SQL Server | npm install mssql |

Drivers are resolved from your workspace (ORIGINAL_CWD), the current directory, or a global install (npm install -g pg) — so a driver installed in your project is found even when NeuralLoom runs from its own package directory. If a driver is missing, the connection test names it and tells you exactly what to install.

🚀 Instant Run via npx (Recommended)

Since NeuralLoom is published on the NPM registry, you can start the orchestrator immediately in any workspace without cloning the code:

npx neural-loom

[!IMPORTANT] Run from a writable directory: NeuralLoom requires a writable working directory to bootstrap its staging environment and rules maps. If launched from a read-only or system directory (such as C:\Program Files\...), the startup script will fail immediately. We recommend creating and running from a dedicated directory like ~/neural-loom (e.g., mkdir ~/neural-loom && cd ~/neural-loom then run npx neural-loom).

Alternatively, you can install it globally on your machine:

# Install globally
npm install -g neural-loom

# Run the command
neural-loom

Once started, open http://localhost:9600 in your browser to start launching and managing your AI coding agent sessions.

[!NOTE] On Windows, ensure you run this command in a terminal that has access to Git Bash (for runner wrapping) and Node/NPM. If npm is not in your global path, you can prepend the path:

$env:Path = "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VisualStudio\NodeJs;" + $env:Path
npx neural-loom

🏁 Getting Started (Manual Clone & Run)

1. Prerequisites

• Node.js: Version 18 or 20 (Required to compile node-pty).
• Windows Build Tools: If running on Windows, compile dependencies using Visual Studio Build Tools (C++ development workload).
• Git Bash for Windows: Ensure Git Bash is installed (used to safely wrapper shell prompts for node-pty).

2. Path Setup (Windows)

Prepend the Visual Studio Node.js build PATH to ensure all sub-PTYs can access standard command configurations. In PowerShell:

$env:Path = "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VisualStudio\NodeJs;" + $env:Path

3. Installation

Clone the repository and install npm packages:

npm install

4. Running the Dev Server

Launches the Next.js app and the background WebSocket gateway concurrently:

npm run dev

Open http://localhost:9600 to launch your dashboard.

5. Compiling for Production Local Run

To build the bundle and boot up the production server locally:

# Clear any lock-induced cache
rm -Force -Recurse .next

# Build the project
npm run build

# Start production server
npm run start

📂 Project Directory Structure

neural-loom/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── context/          # Claude & Aider wizard launchers persistence API
│   │   │   ├── files/            # File tree explorer and editor actions (read/write/delete)
│   │   │   ├── git/              # Porcelain status and diff reader
│   │   │   └── sessions/         # Launch, stats, and injection routes
│   │   ├── components/
│   │   │   ├── ClaudeWizard.tsx  # Claude session workspace launch configuration modal
│   │   │   ├── AiderWizard.tsx   # Aider session launch modal (flags and keys)
│   │   │   ├── SshWizard.tsx     # SSH VM credential tester
│   │   │   ├── IdeLayout.tsx     # Workspace controller (Tab switcher, Split Terminal)
│   │   │   └── TerminalConsole.tsx # xterm.js socket bridge wrapper
│   │   ├── page.tsx              # Main dashboard launcher view
│   │   └── layout.tsx            # Theme wrapper and HTML document
│   └── lib/
│       └── agents/
│           ├── AgentRunner.ts    # Base class parsing logs and piping buffers
│           ├── ClaudeRunner.ts   # Local Claude Code process configuration
│           ├── DockerRunner.ts   # Alpine sandbox launcher mounting workspaces
│           ├── SSHRunner.ts      # VM CLI connector
│           ├── WebSocketServer.ts # WS Gateway forwarding user inputs to terminals
│           └── SessionManager.ts # Session lifecycles (resume, start, kill)
└── .ai/
    └── neural-loom/              # Local persisted runtime DB (claude.json, aider.json, ssh.json)

🛠️ Troubleshooting

EPERM errors during npm run build

On Windows, sometimes system processes lock the .next compilation folder. Run the following clean script before rebuilding:

Remove-Item -Recurse -Force .next
npm run build

Git Bash not found

If Git Bash is installed in a non-standard directory, set the path explicitly in your environment variables:

$env:NEURAL_LOOM_BASH_PATH = "C:\Your\Path\To\bash.exe"