workspace

Imported from bilyfoster/workspace (AGENTS.md). Install upstream with npx skills add bilyfoster/workspace. Copyright stays with the author.

Workspace v1.6.2 - Agent Documentation

Overview

The Workspace is a multi-agent AI orchestration system running on macOS bare metal with Ollama local LLMs. It uses thread-based agents (not processes) for shared memory access.

New in v1.5.0:

• Manager Agent (🎩) - Primary point of contact and overseer
• Dynamic Agent Creation - Create new agents on-the-fly from templates or custom
• Thinking Animations - Visual indicators when agents are processing
• Full visibility into all agent activities

Previous features:

• Per-agent resource monitoring (CPU, memory)
• Individual agent management controls
• Better status icons and activity indicators

Architecture

Core Components

• WorkspaceOrchestrator: Central coordinator, singleton pattern
• AgentRunner: Thread-based agent execution with AgentSoul identity
• MessageBus: In-memory pub/sub for agent communication
• MissionManager: Task/mission CRUD with JSON persistence
• OllamaClient: Local LLM integration (qwen3.5:9b, dolphin3, gemma3)

Agent Identity System

Each agent has a soul.md file defining:

• name: Display name
• role: Functional role (Strategist, Copywriter, etc.)
• model: Ollama model to use
• essence: Personality/core identity
• skills: List of capabilities

Available Agents

Core Team

Dynamic Templates (v1.5.0)

Dashboard Interface (v1.6.2)

HUD Panel (Top)

┌─────────────────────────────────────────────────────────────────┐
│  🎯 Workspace HUD    Agents  Working  Alerts  Missions  Tasks   │
│                      5        2⚡       0🔴      1        47     │
├─────────────────────────────────────────────────────────────────┤
│  [🎩 Manager]  [🎨 Pixel]  [💻 Code]  [📊 Data]  [⚖️ Legal]     │  ← Click to chat
│   🟢 IDLE       🟡 WORKING   🟢 IDLE     🟢 IDLE     🔴 ERROR    │
└─────────────────────────────────────────────────────────────────┘

Main Pages

🏠 Dashboard - Main chat interface

• Chat with Manager or selected agent
• Real-time message display
• Thinking indicators

🤖 Agent Control - Agent management

• View active agents with details
• Spawn individual agents or squads
• Create custom agents from templates
• Respawn/kill agents

📋 Missions - Mission control

• View all missions with progress bars
• Execute missions with visible feedback
• Export mission results
• Create new missions with task assignment

📜 Logs & Debug - Activity monitoring (NEW v1.6.2)

┌──────────────────────────────────────────────┐
│  Filter: [All ▼]    [🧹 Clear Logs]          │
├──────────────────────────────────────────────┤
│  [10:23:45] Spawned Manager        (green)   │
│  [10:24:12] Starting mission: Q1 Launch     │
│  [10:24:15] Shuri working on: Positioning   │
│  [10:25:01] Shuri completed task            │
│  [10:25:30] ERROR: Code not responding      │
└──────────────────────────────────────────────┘

• Real-time logging of all system activity
• Filter by level: All, Info, Success, Warning, Error
• Debug info: Agent details, system resources, message bus status

2. Chat - 1-on-1 agent conversations (30s timeout)
3. Group Chat - Multi-agent discussions
4. Spawn Agents - Agent management (respawn/kill)
5. Missions - Task board with parallel execution
6. Handoffs - Manual/auto handoff management
7. Alerts - System notifications
8. Analytics - Activity tracking
9. Logs - Debug and error logs
10. System - Settings and configuration

Key Features (v1.6.0)

Parallel Task Execution

orchestrator.execute_mission_parallel(mission_id)
# Runs all pending tasks concurrently with ThreadPoolExecutor

Agent Health Monitor (NEW v1.7.0)

The Manager now has a heartbeat that monitors all agents:

Health States:

• ✅ Healthy - Agent functioning normally
• ☕ Idle - Agent ready for work
• ⚡ Working - Agent processing task
• ⏱️ Stuck - Working >5 minutes (potential issue)
• 🔴 Error - Agent encountered error
• 💤 Offline - Agent not running

Auto-Remediation:

• Detects stuck agents (working too long)
• Auto-respawns agents on critical errors (up to 2 retries)
• Logs all health events for visibility
• Suggests troubleshooting actions

Dashboard Integration:

• HUD shows alert banner when issues detected
• Agent cards show health state with colors
• Agent Control page shows detailed diagnostics
• Logs & Debug page tracks health history

HUD Dashboard (v1.6.1)

• Collapsible panel - Save space when needed
• Real-time metrics - Agent count, working, alerts, missions, tasks
• Agent mini-cards - Click to chat, color-coded by status
• Working navigation - All sidebar buttons functional

Manager Overseer

• Manager Agent (🎩) as your primary point of contact
• Full visibility into all agent activities
• Natural language commands: "Who's working on what?"
• Manager can spawn agents and create new roles
• Live activity feed with thinking indicators

Dynamic Agent Creation (NEW)

Create new agents on-the-fly:

# From template
agent_factory.create_agent_from_template("data_analyst", "Atlas")

# Custom creation
agent_factory.create_custom_agent(
    name="Zeus",
    role="Cloud Architect",
    avatar="☁️",
    essence="Expert in cloud infrastructure...",
    skills=["AWS", "Terraform", "Kubernetes"]
)

Visual Processing Indicators (NEW)

• 🧠 Thinking animation with bouncing dots
• Status badges with glow effects
• Real-time "working on..." indicators
• Brain pulse animation during processing

Resource Monitoring

• Real-time CPU and memory tracking per agent
• System-wide resource summary
• Resource usage charts in Analytics
• Visual resource bars in Dashboard

Mission Export

• Markdown format: ./exports/Mission_Name_YYYYMMDD_HHMMSS.md
• JSON format available
• Includes all task results

Auto-Handoff Detection

• Parses agent responses for handoff keywords
• Suggests next agent based on task type
• Beta feature, may need manual adjustment

Usage Examples

Chat with Manager (NEW)

The Manager is your primary point of contact:

orch = get_orchestrator()
orth.spawn_agent('manager')

# Ask about team status
response = orch.chat_with_agent_sync('Manager', "Who's working on what?")

# Spawn a squad
response = orch.chat_with_agent_sync('Manager', "Spawn the creative squad")

# Create a new agent
response = orch.chat_with_agent_sync('Manager', "Create a data analyst named Atlas")

Dynamic Agent Creation (NEW)

from shared.agent_factory import agent_factory

# From template
soul_path = agent_factory.create_agent_from_template(
    template_key="data_analyst",
    name="Atlas"
)

# Custom agent
soul_path = agent_factory.create_custom_agent(
    name="Zeus",
    role="Cloud Architect", 
    avatar="☁️",
    essence="Cloud infrastructure expert...",
    skills=["AWS", "Terraform", "Kubernetes"],
    model="qwen3-coder"
)

# Spawn the new agent
orch.spawn_agent(soul_path.parent.name)

Spawn an Agent

from workspace_orchestrator import get_orchestrator
orch = get_orchestrator()
agent = orch.spawn_agent('shuri')  # Returns AgentRunner thread

Create Mission

mission = orch.create_mission(
    title="Project Name",
    description="Goal description",
    tasks=[
        {"description": "Task 1", "assigned_to": "Shuri"},
        {"description": "Task 2", "assigned_to": "Quill"}
    ]
)

Execute Mission

# Parallel execution (all tasks at once)
orth.execute_mission_parallel(mission.id)

# Individual task assignment
orch.assign_task("Shuri", "Task description", mission.id, task.id)

Chat with Agent

# Sync chat with 30s timeout
response = orch.chat_with_agent_sync(agent_id, "Hello")

Testing

QA Tests (12/12 passing)

Run: python3 test_full_qa.py

• Agent spawning
• Mission creation
• Task assignment
• Chat functionality
• Export generation

Project Test

Full end-to-end with creative team:

python3 << 'EOF'
from workspace_orchestrator import get_orchestrator
orch = get_orchestrator()

# Spawn team
team = ['shuri', 'pixel', 'code', 'quill']
for name in team:
    orch.spawn_agent(name)

# Create mission
mission = orch.create_mission(
    title="Landing Page Project",
    description="Create landing page copy",
    tasks=[
        {"description": "Write product positioning", "assigned_to": "Shuri"},
        {"description": "Write landing page headline", "assigned_to": "Quill"},
        {"description": "Design mockup", "assigned_to": "Pixel"}
    ]
)

# Execute
orch.execute_mission_parallel(mission.id)
EOF

Known Issues

1. Chat History Empty: Persistence logic needs verification
2. Activity Tracker: No events captured during execution
3. Timeout: Long tasks may hit 60s default timeout
4. Memory: Agent memory files not populating

File Locations

Configuration

Environment variables in .env:

OLLAMA_HOST=http://herbie:11434
WORKSPACE_DATA_DIR=./data

Version History

• v1.7.0 (Current): Agent Health Monitor with auto-remediation
• v1.6.2: Logs & Debug page, mission visibility, improved HUD
• v1.6.1: Collapsible HUD, fixed navigation, cleaner UI
• v1.6.0: HUD redesign, floating dashboard, chat-first interface
• v1.5.0: Manager Overseer, dynamic agent creation, thinking animations
• v1.4.0: Resource monitoring, individual agent controls, better UX
• v1.3.0: MVP Complete - Parallel execution, exports, handoffs
• v1.2.0: Thread-based agents, persistent chat
• v1.1.0: Mission system, basic task execution
• v1.0.0: Initial release, single agent chat