⊘ Deadline Agent

This is a prototype of multi-agent orchestrator. It treats every task as an agentic AI session in a distributed system. The larger concept of this app described in Deadline-Agent-Concept.md

Overview

⊘ Deadline Agent brings together concepts from task management systems (like Jira/Linear) and resource orchestration platforms (like Thinkbox Deadline) to create a developer-focused productivity tool. The application provides:

• Task & Subtask Management: Organize work into hierarchical tasks with rich metadata
• Tasks execution via remote CLI process: Spawn and manage terminal sessions across multiple servers
• Session Persistence: Terminal sessions survive browser refreshes and client disconnections
• Real-time Orchestration: Broadcast commands to multiple terminals simultaneously

Version: 0.1.0 (prototype/early stage)

Overall context

Functionality

The app works as a FE client (next.js) and BE server (node.js) running together.

For the servers' docs, use corresponding README.md

FE client quick note. Only critical functionality has been tested in this prototype: ability to work with multiple local/remote CLI agents via JIRA/TODO -alike UI. A set of feature that may turn this prototype into a powerful system described in Deadline-Agent-Concept.md

Getting Started

1. Install Dependencies

npm install

2. Configure Servers

Edit src/config/server.ts to configure your WebSocket server endpoints:

export const PRIMARY_SERVER_CONFIG = {
  id: "local-3001",
  name: "Local Macbook AIR",
  host: "192.168.4.85",  // Update with your local IP
  port: 3001,
  wsPath: "/ws"
};

export const SECONDARY_SERVER_CONFIG = {
  id: "remote-3001",
  name: "Remote Mac Mini M5",
  host: "192.168.4.91",  // Update with your remote IP
  port: 3001,
  wsPath: "/ws"
};

3. Start Backend Server(s)

The frontend requires agent-notes-server to be running. Navigate to the server directory and start it:

cd ../agent-notes-server
npm install
npm run dev  # or npm start for production

The server will start on port 3001 by default. You can run multiple instances on different machines.

4. Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

Project Structure

agent-notes-proto/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── page.tsx            # Main dashboard
│   │   ├── layout.tsx          # Root layout
│   │   └── globals.css         # Theme CSS variables
│   │
│   ├── components/
│   │   ├── ui/                 # Radix UI wrapped components
│   │   └── tasks/              # Task management components
│   │
│   ├── modules/
│   │   └── terminal-module/    # Self-contained terminal system (30 files)
│   │       ├── TerminalModule.tsx
│   │       ├── components/
│   │       ├── store/
│   │       ├── types/
│   │       └── utils/
│   │
│   ├── store/                  # Zustand state management
│   │   ├── useTaskStore.ts     # Tasks, subtasks, projects
│   │   ├── useUIStore.ts       # Layout state
│   │   └── types.ts            # Type definitions
│   │
│   ├── hooks/                  # Custom React hooks
│   ├── lib/                    # Utilities and constants
│   └── config/                 # Server configurations
│
├── e2e/                        # Playwright test suite
│   └── tests/
│       ├── 01-task-crud.spec.ts
│       ├── 02-subtask-management.spec.ts
│       ├── 03-terminal-sessions.spec.ts
│       ├── 04-data-persistence.spec.ts
│       ├── 05-drag-drop.spec.ts
│       ├── 06-selection-state.spec.ts
│       └── 07-notes-system.spec.ts
│
├── public/                     # Static assets
├── Deadline-Agent-Concept.md   # Product vision document
└── theme-customization-guide.md # Theming instructions

Architecture

State Management

Zustand Stores with localStorage persistence:

• useTaskStore: Tasks, subtasks, projects, and selection state
• useUIStore: Panel layout and resize state
• useTerminalStore: Terminal sessions and WebSocket connections

Terminal Module Architecture

The terminal module is a self-contained, pluggable component that can be imported into any React application:

Terminal Module
├── Multi-server WebSocket management
├── PTY session lifecycle (create/destroy/reattach)
├── Hidden terminal pool for performance
├── Broadcast input to all sessions
├── Persistent terminal state across re-renders
└── Full xterm.js integration

WebSocket Protocol

Client → Server Messages:

• create_session: Spawn new terminal with command
• prompt: Send input to terminal
• resize: Change terminal dimensions
• destroy_session: Kill a session
• detach_session: Persist session across disconnects
• reattach_session: Reconnect to detached session

Server → Client Messages:

• output: Terminal output data
• session_created: Confirmation with session ID
• session_destroyed: Cleanup notification
• error: Error messages

Usage

Creating a Task

1. Click the quick-add form in the left column
2. Enter task title and select project
3. Optionally configure: priority, type, scope, difficulty
4. Click "Add Task"

Adding Subtasks

1. Select a task from the list
2. In the task details panel (middle column), click "Add Subtask"
3. Enter subtask title and description
4. Configure status and working directory

Managing Terminal Sessions

1. Select a subtask to open the details panel (right column)
2. In the terminal section, choose a server
3. Click "Create Session" and configure:
   • Command to run
   • Arguments
   • Working directory
4. Use the broadcast input to send commands to all sessions
5. Sessions persist across page refreshes

Drag-and-Drop Reordering

• Tasks: Drag task cards in the left column to reorder
• Subtasks: Drag subtask items within a task to reorder

Export/Import Data

1. Click the menu icon (three dots) in the header
2. Select "Export to JSON" to download a backup
3. Select "Import from JSON" to restore data

Development Commands

Quality Assurance

npm run check       # Run Biome linter
npm run typecheck   # TypeScript type checking
npm run fix         # Auto-fix linting issues
npm run format      # Auto-format code
npm run quality     # Run all checks + build

Build & Deployment

npm run build       # Production build
npm run start       # Start production server

Testing

npm run test:e2e           # Run all E2E tests
npm run test:e2e:ui        # Run with interactive UI
npm run test:e2e:debug     # Run in debug mode
npm run test:e2e:report    # View HTML test report

Configuration

Theme Customization

The app uses OKLCH color space for precise color control. Edit src/app/globals.css to customize:

:root {
  --background: oklch(98% 0 0);
  --foreground: oklch(9% 0.005 286);
  --primary: oklch(47% 0.24 264);
  /* ... more variables */
}

.dark {
  --background: oklch(13% 0.01 286);
  --foreground: oklch(98% 0 0);
  /* ... dark mode overrides */
}

See theme-customization-guide.md for detailed instructions.

Terminal Defaults

Edit terminal behavior in the terminal module store:

• Default rows/columns
• Reconnection behavior
• Connection timeout
• Server configurations

Data Persistence

All data is automatically persisted to localStorage:

• task-management-storage: Tasks, subtasks, projects, selections
• ui-storage: Panel layout state
• terminal-storage: Terminal metadata

Data survives browser refreshes and session restarts.

Testing

The project includes a comprehensive Playwright E2E test suite covering:

• Task CRUD operations
• Subtask management
• Terminal session creation and management
• Data persistence and export/import
• Drag-and-drop functionality
• Selection state management
• Notes system

Tests run on Chromium, Firefox, and WebKit.

Related Projects

• agent-notes-server: WebSocket PTY server for terminal session management

Documentation

• Deadline-Agent-Concept.md: Product vision and architecture
• theme-customization-guide.md: Detailed theming instructions