ClaudeNest

Remote Claude Code orchestration platform -- control, coordinate, and scale Claude Code instances from anywhere.

---

What is ClaudeNest?

ClaudeNest turns Claude Code into a remotely accessible, multi-agent platform. Pair any machine running the agent daemon, then create and manage terminal sessions from a web dashboard or native mobile app. When multiple Claude instances work on the same project, ClaudeNest coordinates them through shared context (RAG), file locking, and an atomic task system.

---

Features

Remote Terminal Sessions

Real-time terminal access via xterm.js and WebSocket (Laravel Reverb). Full PTY support with resize, search, and WebGL rendering.

Machine Pairing

Six-character pairing codes (XXX-XXX) generated by the agent. Enter the code in the dashboard or mobile app to link a machine instantly.

Multi-Agent Orchestration

Run multiple Claude Code instances on the same project. Each instance can claim tasks, lock files, and share context without conflicts.

Context RAG

pgvector-powered retrieval-augmented generation. Project context is embedded (384-dimensional vectors via bge-small-en-v1.5) and retrieved by semantic similarity so every instance has the right information.

File Locking

Distributed file locks prevent two agents from editing the same file. Locks expire automatically and can be force-released when needed.

Task Coordination

Atomic task claiming ensures no two instances pick up the same work. Tasks track status, dependencies, completion summaries, and modified files.

Skills and MCP Servers

Discover, register, and toggle Claude Code skills per machine. Manage MCP (Model Context Protocol) servers and execute their tools remotely.

Authentication

Magic link login, plus OAuth via Google and GitHub. Token-based API access for agents and integrations.

Project Management

Built-in Epics, Sprints, and Kanban boards with burndown charts. Organize tasks into features, plan time-boxed sprints, and track velocity across your multi-agent projects.

Planning Agent

AI-powered conversational project planning. Describe what you need, and the Planning Agent decomposes it into structured tasks, assigns them to the right agents, and executes changes in atomic database transactions.

Runner Agent

Automated project health monitoring and sprint tracking. The Runner Agent continuously checks task statuses, flags blockers, updates sprint progress, and surfaces insights so nothing falls through the cracks.

Smart File Locking

Atomic lock acquisition with task-lock integration and heartbeat auto-extend. Locks are tied to active tasks and automatically renewed while work is in progress, then released on task completion.

Mobile Apps

Native iOS and Android apps built with React Native. Monitor machines, manage sessions, and coordinate agents on the go.

---

Architecture

flowchart TB
    subgraph Clients
        Web["Web Dashboard\nVue 3 + xterm.js"]
        Mobile["Mobile App\nReact Native"]
        Agent["Agent Daemon\nNode.js + node-pty"]
    end

    subgraph Server["ClaudeNest Server -- Laravel 12"]
        API["REST API\nSanctum Auth"]
        WS["WebSocket\nReverb"]
        RAG["RAG Engine\nEmbeddings + Search"]
    end

    subgraph Infra["Infrastructure"]
        PG["PostgreSQL 16\n+ pgvector"]
        Redis["Redis 7\nCache / Queues"]
        Ollama["Ollama\nbge-small-en + Mistral 7B"]
    end

    Web -->|HTTPS| API
    Web -->|WSS| WS
    Mobile -->|HTTPS| API
    Mobile -->|WSS| WS
    Agent -->|WSS| WS

    API --> PG
    WS --> Redis
    RAG --> PG
    RAG --> Ollama

Loading

Project Management System

Epics group related tasks into named features with progress tracking visible across the board. Sprints add time-based planning: each sprint has a start and end date, a velocity target, and a live burndown chart generated from task completion events.

The Planning Agent receives the full project context (summary, architecture, active tasks, current sprint) before each conversation turn. Every action it proposes — creating tasks, moving them between epics, starting a sprint — executes inside an atomic database transaction, so the project state is always consistent even when multiple agents are running simultaneously.

The Runner Agent runs on a schedule and does not require user interaction. It scans open tasks for stale statuses, detects blocked items whose blockers have since resolved, recalculates sprint burndown, and posts structured health summaries back to the project activity log.

---

Tech Stack

Layer	Technology	Version
Backend	Laravel (PHP 8.4+)	13
Frontend	Vue.js (Composition API)	3.5
Build	Vite + Rolldown (Rust)	8.0
State (Web)	Pinia	3.0
Terminal	xterm.js + WebGL addon	5.5
Styling	Tailwind CSS (CSS-first)	4.1
TypeScript	Strict mode	6.0
WebSocket	Laravel Reverb	1.10
Auth	Laravel Sanctum + Socialite	4.x
Database	PostgreSQL + pgvector	16+
Cache/Queue	Redis	7+
Agent	Node.js + TypeScript + node-pty	24 LTS
Mobile	Expo 55, React Native, React 19	0.83
Mobile State	Zustand	5.0
Mobile Animations	Reanimated (New Architecture)	4.2
Embeddings	Ollama (bge-small-en-v1.5)	--
Summarization	Ollama (Mistral 7B)	--

---

Quick Start

Prerequisites

• PHP 8.3+, Composer
• Node.js 20+, npm
• PostgreSQL 16+ with the pgvector extension
• Redis 7+
• Ollama (optional, for RAG features)

Option A -- Docker

git clone https://github.com/QrCommunication/claudenest.git
cd claudenest

cp packages/server/.env.example packages/server/.env
docker compose up -d

docker compose exec server php artisan key:generate
docker compose exec server php artisan migrate

See docs/DEPLOYMENT-DOCKER.md for the full Docker guide.

Option B -- Local development

git clone https://github.com/QrCommunication/claudenest.git
cd claudenest

# Server setup
cd packages/server
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate

# Start everything (server, Vite, Reverb, queue worker)
composer dev

The composer dev script launches four processes in parallel:

Process	URL
Laravel server	http://localhost:8000
Vite dev server	http://localhost:5173
Reverb WebSocket	ws://localhost:8080
Queue worker	(background)

See docs/DEPLOYMENT-BAREMETAL.md for production setup.

Agent setup

cd packages/agent
npm install
npm run dev

Mobile setup

cd packages/mobile
npm install

# iOS
npm run pod-install
npm run ios

# Android
npm run android

---

Project Structure

claudenest/
  packages/
    server/                   Laravel 12 + Vue 3 SPA
      app/
        Http/Controllers/Api/   REST API controllers
        Models/                 Eloquent models (UUID, pgvector)
        Services/               Business logic (RAG, MCP, Skills)
        Events/                 Broadcast events
      resources/js/             Vue 3 SPA
        components/             UI components by domain
        composables/            Vue composables
        pages/                  Page-level components
        stores/                 Pinia stores
      routes/
        api.php                 API routes
        channels.php            Broadcast channels
      database/migrations/      Schema migrations

    agent/                    Node.js daemon
      src/
        sessions/               PTY management
        websocket/              WebSocket client
        discovery/              Skills & MCP discovery
        context/                Context sync client

    mobile/                   React Native app
      src/
        screens/                App screens
        components/             Shared components
        stores/                 Zustand stores
        services/               API & WebSocket clients

  docs/                       Extended documentation
  scripts/                    Install & setup scripts
  branding/                   Logos, banners, brand guidelines

---

API Reference

The most commonly used endpoints are listed below. For the full API reference, see docs/API.md.

Authentication

Method	Endpoint	Description
POST	/api/auth/login	Login with credentials
POST	/api/auth/register	Register new user
GET	/api/auth/me	Current user profile
GET	/api/auth/{provider}/redirect	OAuth redirect (google, github)

Machines

Method	Endpoint	Description
GET	/api/machines	List paired machines
POST	/api/machines	Register a machine
GET	/api/machines/{id}	Machine details
POST	/api/machines/{id}/regenerate-token	Regenerate auth token

Sessions

Method	Endpoint	Description
POST	/api/machines/{id}/sessions	Create terminal session
POST	/api/sessions/{id}/input	Send input to session
POST	/api/sessions/{id}/resize	Resize PTY
DELETE	/api/sessions/{id}	Terminate session

Multi-Agent (Projects, Tasks, Locks)

Method	Endpoint	Description
POST	/api/machines/{id}/projects	Create shared project
POST	/api/projects/{id}/context/query	Semantic context search
POST	/api/projects/{id}/tasks	Create task
POST	/api/tasks/{id}/claim	Claim task (atomic)
POST	/api/projects/{id}/locks	Lock a file
POST	/api/projects/{id}/locks/release	Release file lock

Epics

Method	Endpoint	Description
GET	/api/projects/{id}/epics	List epics
POST	/api/projects/{id}/epics	Create epic
PATCH	/api/epics/{id}	Update epic
DELETE	/api/epics/{id}	Delete epic
POST	/api/projects/{id}/epics/reorder	Reorder epics

Sprints

Method	Endpoint	Description
GET	/api/projects/{id}/sprints	List sprints
POST	/api/projects/{id}/sprints	Create sprint
PATCH	/api/sprints/{id}	Update sprint
POST	/api/sprints/{id}/start	Start sprint
POST	/api/sprints/{id}/complete	Complete sprint
GET	/api/sprints/{id}/burndown	Burndown chart data

Planning Agent

Method	Endpoint	Description
GET	/api/projects/{id}/planning/context	Full project context for planning
POST	/api/projects/{id}/planning/execute	Execute planning action (atomic)

Runner Agent

Method	Endpoint	Description
GET	/api/projects/{id}/runner/health	Project health report
POST	/api/projects/{id}/runner/auto-update	Trigger status auto-update
GET	/api/projects/{id}/runner/progress	Sprint progress and velocity

---

Configuration

Key environment variables (packages/server/.env)

# Database (PostgreSQL + pgvector required)
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=claudenest

# WebSocket (Laravel Reverb)
REVERB_APP_ID=claudenest
REVERB_APP_KEY=your-reverb-key
REVERB_APP_SECRET=your-reverb-secret
REVERB_SERVER_PORT=8080

# OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# AI Models (optional, for RAG)
OLLAMA_HOST=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=bge-small-en-v1.5
OLLAMA_SUMMARIZATION_MODEL=mistral:7b

See docs/AI-MODELS.md for Ollama setup and model configuration.

Agent configuration (packages/agent/config.json)

{
  "serverUrl": "ws://localhost:8080",
  "machineToken": "mn_...",
  "claudePath": "/usr/local/bin/claude",
  "sessions": { "maxSessions": 10 }
}

---

Development

Server

cd packages/server

# Start all services
composer dev

# Run tests
php artisan test

# Lint PHP
./vendor/bin/pint

# Type-check Vue/TS
npm run typecheck

Agent

cd packages/agent

npm run dev          # Watch mode
npm run build        # Compile TypeScript
npm run test         # Run tests
npm run typecheck    # Type check

Mobile

cd packages/mobile

npm start            # Metro bundler
npm run ios          # Run on iOS simulator
npm run android      # Run on Android emulator
npm run typecheck    # Type check

---

Deployment

Production deployment guides:

• Docker: docs/DEPLOYMENT-DOCKER.md
• Bare metal: docs/DEPLOYMENT-BAREMETAL.md
• Domain setup: docs/DOMAINS.md

An automated install script is available for Ubuntu/Debian servers:

./scripts/install-server.sh

---

Documentation

Technical (Developers)

Document	Description
CLAUDE.md	AI agent reference — single source of truth for the codebase
CHANGELOG.md	All notable changes (Keep a Changelog format)
docs/ARCHITECTURE.md	System design and technical reference
docs/API.md	Full API documentation
docs/AI-MODELS.md	Ollama models and RAG configuration
docs/DEPLOYMENT-DOCKER.md	Docker deployment guide
docs/DEPLOYMENT-BAREMETAL.md	Bare-metal production setup
docs/DOMAINS.md	Domain and DNS configuration
docs/CONTRIBUTING.md	Contribution guidelines
docs/audit-docs.md	Documentation inventory and gap analysis

Guides (Users)

Document	Description
Task Coordination	Epics, Sprints, subtasks, Planning Agent guide
File Locking	Atomic locks, task integration, heartbeat
Online Docs	Full documentation portal

Marketing & Business

Document	Description
docs/marketing/one-pager.md	Product pitch — problem, solution, key numbers
docs/marketing/feature-highlights.md	Feature cards with benefits
docs/marketing/analyse-business.md	Business analysis — personas, use cases, competitive advantages
branding/BRAND-GUIDELINES.md	Brand identity and assets

---

Contributing

Contributions are welcome. Please read docs/CONTRIBUTING.md before opening a pull request.

---

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

Copyright 2026 Rony Licha / QR Communication.