agentk8 1.0.2 → 1.0.3

package/README.md

@@ -2,64 +2,93 @@
 
 **Multi-Agent Claude Code Terminal Suite**
 
-Orchestrate multiple specialized Claude agents for software development and ML research. Inspired by Boris Cherny's parallel Claude workflow.
-
 ```
-╭─────────────────────────────────────────────────╮
-│  AGENT-K v1.0                                   │
-╰─────────────────────────────────────────────────╯
+╭─────────────────────────────────────────────────────────────────────────────────╮
+│                              AGENT-K v1.0                                       │
+╰─────────────────────────────────────────────────────────────────────────────────╯
+```
 
-You: Implement user authentication with JWT
+Transform your terminal into a team of specialized AI agents. AGENT-K orchestrates multiple Claude instances working in parallel on your software development and ML research tasks.
 
-[Orchestrator] Breaking down task...
-  → Engineer: Implement JWT auth module
-  → Tester: Write auth tests
-  → Security: Review for vulnerabilities
+## What is AGENT-K?
 
-[●] Orchestrator  Coordinating
-[◐] Engineer      Writing src/auth.py...
-[ ] Tester        Waiting
-[ ] Security      Waiting
+AGENT-K extends Claude Code with **multi-agent orchestration**. Instead of a single AI assistant, you get a coordinated team of specialists - each with domain expertise, working together on complex tasks.
 
-You: _
+```
+╭─ You ────────────────────────────────────────────────────────────────────────────╮
+│ Build a secure REST API with user authentication                                 │
+╰──────────────────────────────────────────────────────────────────────────────────╯
+
+╭─ Orchestrator ───────────────────────────────────────────────────────────────────╮
+│ Breaking down task...                                                            │
+│   → Engineer: Implement REST endpoints and JWT authentication                    │
+│   → Tester: Write API integration tests                                          │
+│   → Security: Review for OWASP vulnerabilities                                   │
+│   → Scout: Find latest best practices for JWT in 2025                            │
+╰──────────────────────────────────────────────────────────────────────────────────╯
+
+[●] Orchestrator   Coordinating
+[◐] Engineer       Writing src/api/auth.py...
+[◐] Scout          Searching for JWT best practices...
+[ ] Tester         Waiting for implementation
+[ ] Security       Queued for review
 ```
 
+## Why AGENT-K?
+
+### The Problem
+
+Claude is brilliant, but complex tasks often require:
+- **Multiple perspectives** (implementation, testing, security)
+- **Parallel work** (why write tests sequentially after code?)
+- **Up-to-date information** (Claude's training data becomes stale)
+- **Specialized focus** (security reviews need different prompts than coding)
+
+### The Solution
+
+AGENT-K spawns specialized Claude agents that:
+- **Work in parallel** on different aspects of your task
+- **Coordinate automatically** through a central orchestrator
+- **Stay current** with a dedicated Scout agent for real-time research
+- **Follow best practices** with domain-specific system prompts
+
 ## Features
 
-- **Multi-Agent Orchestration**: Coordinate specialized agents working in parallel
-- **Two Modes**: Software Development and ML Research & Training
-- **Interactive Chat**: Works like `claude` but with a team of specialists
-- **Visual Mode**: tmux-based multi-pane view of all agents
-- **Scout Agent**: Real-time web/GitHub/paper search to stay current
-- **Date Awareness**: Agents know their training data may be outdated
+| Feature | Description |
+|---------|-------------|
+| **Multi-Agent Orchestration** | Coordinate 5-6 specialized agents working in parallel |
+| **Two Modes** | Software Development (default) and ML Research & Training |
+| **Interactive Chat** | Familiar interface like `claude` but with a whole team |
+| **Visual Mode** | tmux-based multi-pane view of all agents working |
+| **Scout Agent** | Real-time web/GitHub/paper search to stay current |
+| **Date Awareness** | Agents know when to verify potentially outdated info |
+| **Focus Mode** | Talk directly to any specialist agent |
+| **File-Based IPC** | Agents coordinate through structured JSON messages |
 
-## Agents
+## Agent Teams
 
 ### Development Mode (Default)
-| Agent | Role |
-|-------|------|
-| **Orchestrator** | Breaks down tasks, coordinates agents |
-| **Engineer** | Implements code, debugging, refactoring |
-| **Tester** | Writes tests, validates implementations |
-| **Security** | Reviews for vulnerabilities, OWASP checks |
-| **Scout** | Searches web/GitHub for current best practices |
+
+| Agent | Specialty |
+|-------|-----------|
+| **Orchestrator** | Task decomposition, coordination, result aggregation |
+| **Engineer** | Code implementation, debugging, refactoring |
+| **Tester** | Unit/integration tests, coverage analysis |
+| **Security** | OWASP vulnerability review, secrets detection |
+| **Scout** | Real-time search for current best practices |
 
 ### ML Mode (`--mode ml`)
-| Agent | Role |
-|-------|------|
-| **Orchestrator** | Manages ML project lifecycle |
-| **Researcher** | Literature review, SOTA analysis |
-| **ML Engineer** | Model implementation, training |
-| **Data Engineer** | Data pipelines, preprocessing |
-| **Evaluator** | Metrics, benchmarking, experiments |
-| **Scout** | Searches arXiv, HuggingFace, Papers With Code |
 
-## Installation
+| Agent | Specialty |
+|-------|-----------|
+| **Orchestrator** | ML project lifecycle management |
+| **Researcher** | Literature review, SOTA analysis, paper summaries |
+| **ML Engineer** | Model implementation, training loops, optimization |
+| **Data Engineer** | Data pipelines, preprocessing, augmentation |
+| **Evaluator** | Metrics, benchmarking, experiment tracking |
+| **Scout** | arXiv, HuggingFace, Papers With Code search |
 
-### Quick Install (Recommended)
-```bash
-curl -sSL https://raw.githubusercontent.com/de5truct0/agentk/main/install.sh | bash
-```
+## Installation
 
 ### Homebrew (macOS/Linux)
 ```bash
@@ -77,7 +106,10 @@ npm install -g agentk8
 pip install agentk8
 ```
 
-> **Note**: Package name is `agentk8` on all registries. The installed command is `agentk`.
+### Quick Install Script
+```bash
+curl -sSL https://raw.githubusercontent.com/de5truct0/agentk/main/install.sh | bash
+```
 
 ### From Source
 ```bash
@@ -86,127 +118,216 @@ cd agentk
 make install
 ```
 
+> **Note**: Package name is `agentk8` on all registries. The installed command is `agentk`.
+
 ## Requirements
 
-- **bash** 4.0+
-- **jq** (JSON processing)
-- **claude** (Claude Code CLI) - [Install here](https://claude.ai/code)
-- **tmux** (optional, for visual mode)
+- **jq** - JSON processing (`brew install jq`)
+- **claude** - Claude Code CLI ([Install here](https://claude.ai/code))
+- **tmux** - Optional, for visual mode (`brew install tmux`)
 
-## Usage
+## Quick Start
 
-### Start Interactive Session
 ```bash
-agentk                    # Dev mode (default)
-agentk --mode ml          # ML mode
-agentk --visual           # With tmux panels
+# Start interactive session
+agentk
+
+# Start ML research mode
+agentk --mode ml
+
+# Start with visual panels (requires tmux)
+agentk --visual
+
+# One-shot task
+agentk -c "Refactor the user service to use async/await"
 ```
 
-### One-Shot Mode
+## Usage
+
+### Interactive Session
+
 ```bash
-agentk -c "Build a REST API for user management"
+$ agentk
+
+╭─────────────────────────────────────────────────╮
+│  AGENT-K v1.0                                   │
+╰─────────────────────────────────────────────────╯
+Mode: Software Development Mode
+
+Type your request or /help for commands.
+
+╭─ You ─────────────────────────────────────────────────
+│
 ```
 
 ### Session Commands
+
 | Command | Description |
 |---------|-------------|
-| `/status` | Show all agent states |
+| `/status` | Show all agent states and current tasks |
 | `/logs <agent>` | View agent output |
 | `/kill <agent\|all>` | Stop agent(s) |
-| `/focus <agent>` | Talk directly to agent |
+| `/focus <agent>` | Talk directly to one agent |
 | `/unfocus` | Return to orchestrator |
-| `/visual` | Toggle tmux view |
+| `/visual` | Toggle tmux panel view |
+| `/clear` | Clear screen |
 | `/help` | Show all commands |
 | `/exit` | End session |
 
-### Scout Commands
+### Scout Commands (Both Modes)
+
 | Command | Description |
 |---------|-------------|
-| `/search <query>` | Web search |
-| `/github <query>` | Search GitHub |
-| `/papers <topic>` | Search papers (ML mode) |
-| `/libs <task>` | Find best libraries |
-| `/sota <topic>` | State-of-the-art |
+| `/search <query>` | Web search for latest info |
+| `/github <query>` | Search GitHub repos and code |
+| `/papers <topic>` | Search arXiv/Semantic Scholar |
+| `/libs <task>` | Find best libraries for task |
+| `/sota <topic>` | Get state-of-the-art approaches |
+
+### ML-Specific Commands
 
-### ML Commands
 | Command | Description |
 |---------|-------------|
-| `/experiment <name>` | Start experiment |
-| `/metrics` | Show metrics |
+| `/experiment <name>` | Start a new experiment |
+| `/metrics` | Show current training metrics |
 | `/tensorboard` | Open TensorBoard |
-| `/huggingface <query>` | Search HF Hub |
+| `/checkpoint` | Save model state |
+| `/compare <e1> <e2>` | Compare experiments |
+| `/huggingface <query>` | Search HuggingFace Hub |
 
 ## Visual Mode
 
+Launch with `--visual` to see all agents in a tmux layout:
+
 ```
-┌───────────────┬───────────────┬───────────────┐
-│  ORCHESTRATOR │   ENGINEER    │    TESTER     │
-├───────────────┼───────────────┼───────────────┤
-│   SECURITY    │     SCOUT     │    [MAIN]     │
-└───────────────┴───────────────┴───────────────┘
+┌───────────────────┬───────────────────┬───────────────────┐
+│   ORCHESTRATOR    │     ENGINEER      │      TESTER       │
+│                   │                   │                   │
+│ Breaking down     │ Implementing      │ Waiting for       │
+│ task into         │ auth module...    │ implementation... │
+│ subtasks...       │                   │                   │
+├───────────────────┼───────────────────┼───────────────────┤
+│     SECURITY      │      SCOUT        │      [MAIN]       │
+│                   │                   │                   │
+│ Queued for        │ Searching JWT     │ You: _            │
+│ review            │ best practices... │                   │
+│                   │                   │                   │
+└───────────────────┴───────────────────┴───────────────────┘
 ```
 
 ## How It Works
 
-1. **You enter a request** in the interactive session
-2. **Orchestrator analyzes** the task and breaks it into subtasks
-3. **Specialist agents** are spawned as Claude subprocesses
-4. Agents work on **your project files** in the current directory
-5. **Results are aggregated** and reported back to you
+```
+                          ┌─────────────┐
+                          │    User     │
+                          └──────┬──────┘
+                                 │
+                                 ▼
+                    ┌────────────────────────┐
+                    │     Orchestrator       │
+                    │  (task decomposition)  │
+                    └───────────┬────────────┘
+                                │
+           ┌────────────────────┼────────────────────┐
+           │                    │                    │
+           ▼                    ▼                    ▼
+   ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+   │   Engineer    │   │    Tester     │   │   Security    │
+   │ (implements)  │   │  (validates)  │   │  (reviews)    │
+   └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
+           │                    │                    │
+           └────────────────────┴────────────────────┘
+                                │
+                                ▼
+                    ┌────────────────────────┐
+                    │    File-Based IPC      │
+                    │ workspace/tasks/*.json │
+                    └────────────────────────┘
+```
 
-Each agent runs as a separate `claude` CLI instance with a specialized system prompt, coordinated through file-based messaging.
+1. **You enter a request** in the interactive session
+2. **Orchestrator analyzes** and breaks it into subtasks
+3. **Specialist agents spawn** as parallel Claude subprocesses
+4. Agents work **on your actual project files**
+5. **Results aggregate** back through the orchestrator
+6. You see the **combined output** with full context
 
 ## Configuration
 
-Create `~/.agentk/config.sh` to customize:
+Create `~/.agentk/config.sh`:
 
 ```bash
-# Use a different model
+# Custom model (default: claude-3-sonnet)
 export AGENTK_MODEL="claude-3-opus-20240229"
 
-# Set log level
-export LOG_LEVEL="debug"
+# Log level: debug, info, warn, error
+export LOG_LEVEL="info"
 
 # Custom workspace location
-export AGENTK_WORKSPACE="/path/to/workspace"
+export AGENTK_WORKSPACE="/custom/path/workspace"
+
+# Parallel agent limit (default: 4)
+export AGENTK_MAX_PARALLEL=6
 ```
 
 ## Project Structure
 
 ```
 agentk/
-├── agentk                # Main CLI
+├── agentk                # Main CLI entry point
 ├── lib/
-│   ├── core.sh          # Core utilities
-│   ├── ui.sh            # Pretty output
+│   ├── core.sh          # Core utilities, logging, date context
+│   ├── ui.sh            # Terminal UI, spinners, chat boundaries
 │   ├── ipc.sh           # Inter-process communication
-│   ├── spawn.sh         # Agent spawning
+│   ├── spawn.sh         # Agent subprocess management
 │   └── visual.sh        # tmux integration
 ├── modes/
 │   ├── shared/
-│   │   └── scout.md     # Scout agent prompt
-│   ├── dev/             # Dev mode agent prompts
-│   └── ml/              # ML mode agent prompts
+│   │   └── scout.md     # Scout agent system prompt
+│   ├── dev/             # Development mode prompts
+│   │   ├── orchestrator.md
+│   │   ├── engineer.md
+│   │   ├── tester.md
+│   │   └── security.md
+│   └── ml/              # ML mode prompts
+│       ├── orchestrator.md
+│       ├── researcher.md
+│       ├── ml-engineer.md
+│       ├── data-engineer.md
+│       └── evaluator.md
 └── workspace/           # Runtime data (gitignored)
+    ├── tasks/           # Task queue (JSON)
+    ├── results/         # Agent outputs
+    ├── logs/            # Agent logs
+    └── experiments/     # ML experiment tracking
 ```
 
 ## Known Limitations
 
-See [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for a full list. Key limitations:
+| Limitation | Workaround |
+|------------|------------|
+| File conflicts when agents edit same file | Use `/focus` to serialize work on critical files |
+| Each agent = separate API call (cost) | Use orchestrator's judgment on when to parallelize |
+| Agents don't share real-time context | Orchestrator maintains shared state in workspace |
+| Rate limiting with many parallel agents | `AGENTK_MAX_PARALLEL` limits concurrent spawns |
+
+## Roadmap
 
-- **File conflicts**: Multiple agents modifying same file
-- **Cost**: Each agent is a separate API call
-- **Context isolation**: Agents don't share real-time context
-- **Rate limiting**: Parallel agents may hit API limits
+- [ ] Web UI dashboard
+- [ ] Custom agent definitions
+- [ ] Persistent conversation history
+- [ ] Cost tracking per agent
+- [ ] Team collaboration mode
+- [ ] Plugin system for custom tools
 
 ## Contributing
 
-Contributions welcome! Please read the contributing guidelines first.
+Contributions welcome!
 
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch (`git checkout -b feature/amazing`)
 3. Make your changes
-4. Run tests: `make test`
+4. Run tests (`make test`)
 5. Submit a pull request
 
 ## License
@@ -215,10 +336,18 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ## Acknowledgments
 
-- Inspired by [Boris Cherny's Claude Code workflow](https://x.com/bcherny)
+- Inspired by [Boris Cherny's parallel Claude workflow](https://x.com/bcherny)
 - Built for the Claude Code community
 - Powered by [Anthropic's Claude](https://anthropic.com)
 
 ---
 
-**AGENT-K** - Because one Claude is good, but a team of Claudes is better.
+<p align="center">
+<strong>AGENT-K</strong> - Because one Claude is good, but a team of Claudes is better.
+</p>
+
+<p align="center">
+<a href="https://github.com/de5truct0/agentk">GitHub</a> |
+<a href="https://www.npmjs.com/package/agentk8">npm</a> |
+<a href="https://pypi.org/project/agentk8/">PyPI</a>
+</p>

package/agentk

@@ -297,7 +297,10 @@ cmd_scout() {
     fi
 
     local scout_task="$cmd: $query"
-    print_info "Scout is searching..."
+
+    # Show Scout response box
+    print_agent_response_start "Scout"
+    printf "${CYAN}│${RESET} Searching: %s\n" "$query"
 
     # Create task for scout
     local task_id
@@ -307,7 +310,7 @@ cmd_scout() {
     spawn_agent "scout" "$task_id" "$AGENTK_MODE"
 
     # Wait for result
-    print_info "Waiting for Scout..."
+    printf "${CYAN}│${RESET} ${DIM}Processing...${RESET}\n"
     watch_task "$task_id" 120
 
     # Display result
@@ -316,9 +319,10 @@ cmd_scout() {
     if [[ -f "$result_file" ]]; then
         local output
         output=$(jq -r '.output' "$result_file")
-        echo
-        echo "$output"
+        print_chat_content "$output" "${CYAN}│${RESET}"
     fi
+
+    print_agent_response_end
 }
 
 cmd_ml() {
@@ -408,6 +412,8 @@ run_interactive() {
 
         # Check for command
         if [[ "$input" == /* ]]; then
+            # Close user input box for commands
+            print_user_message_end
             local cmd="${input%% *}"
             local args="${input#* }"
             [[ "$cmd" == "$args" ]] && args=""
@@ -415,11 +421,15 @@ run_interactive() {
             continue
         fi
 
+        # Close user input box
+        print_user_message_end
+
         # Regular input - send to orchestrator (or focused agent)
         local target_agent="${FOCUSED_AGENT:-orchestrator}"
 
-        echo
-        print_orchestrator_message "Analyzing task..."
+        # Show agent response box
+        print_agent_response_start "Orchestrator"
+        printf "${CYAN}│${RESET} Analyzing task...\n"
 
         # Create task
         local task_id
@@ -428,7 +438,7 @@ run_interactive() {
         # For now, spawn the agent interactively
         spawn_agent_interactive "$target_agent" "$AGENTK_MODE" "$input"
 
-        echo
+        print_agent_response_end
     done
 }
 
@@ -446,15 +456,23 @@ run_one_shot() {
 
     print_banner
     print_mode_banner "$AGENTK_MODE"
-    print_task "$prompt"
+
+    # Show user input with chat boundaries
+    print_user_input_box "$prompt"
 
     # Create task for orchestrator
     local task_id
     task_id=$(create_task "" "orchestrate" "orchestrator" "$prompt" 1)
 
+    # Show orchestrator response
+    print_agent_response_start "Orchestrator"
+    printf "${CYAN}│${RESET} Processing your request...\n"
+
     # Spawn orchestrator interactively
     spawn_agent_interactive "orchestrator" "$AGENTK_MODE" "$prompt"
 
+    print_agent_response_end
+
     # Cleanup
     end_session
 }

package/lib/core.sh

@@ -8,7 +8,7 @@ set -euo pipefail
 # CONSTANTS
 # =============================================================================
 
-AGENTK_VERSION="1.0.2"
+AGENTK_VERSION="1.0.3"
 AGENTK_ROOT="${AGENTK_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
 AGENTK_WORKSPACE="${AGENTK_ROOT}/workspace"
 CLAUDE_KNOWLEDGE_CUTOFF="2024-04"

package/lib/ui.sh

@@ -282,41 +282,136 @@ print_progress_bar() {
     printf "${RESET} %3d%%\n" "$percent"
 }
 
+# =============================================================================
+# CHAT UI - Claude Code Style
+# =============================================================================
+
+# Chat message boundaries
+CHAT_USER_PREFIX="╭─"
+CHAT_USER_SUFFIX="─╮"
+CHAT_AGENT_PREFIX="├─"
+CHAT_AGENT_SUFFIX="─┤"
+CHAT_END="╰"
+CHAT_CONTINUE="│"
+
+print_chat_divider() {
+    local width
+    width=$(get_terminal_width)
+    local line_width=$((width - 4))
+    printf "${DIM}%s%${line_width}s%s${RESET}\n" "├" "" "┤" | tr ' ' '─'
+}
+
+print_user_message_start() {
+    local width
+    width=$(get_terminal_width)
+    local line_width=$((width - 12))
+    echo
+    printf "${GREEN}╭─ You ${RESET}${DIM}"
+    printf "%${line_width}s" | tr ' ' '─'
+    printf "${RESET}\n"
+}
+
+print_user_message_end() {
+    local width
+    width=$(get_terminal_width)
+    printf "${DIM}╰"
+    printf "%$((width - 2))s" | tr ' ' '─'
+    printf "${RESET}\n"
+}
+
+print_agent_response_start() {
+    local agent="${1:-Agent}"
+    local width
+    width=$(get_terminal_width)
+    local agent_label=" $agent "
+    local line_width=$((width - ${#agent_label} - 4))
+    echo
+    printf "${CYAN}╭─${BOLD}${agent_label}${RESET}${DIM}"
+    printf "%${line_width}s" | tr ' ' '─'
+    printf "${RESET}\n"
+}
+
+print_agent_response_end() {
+    local width
+    width=$(get_terminal_width)
+    printf "${DIM}╰"
+    printf "%$((width - 2))s" | tr ' ' '─'
+    printf "${RESET}\n"
+}
+
+print_chat_content() {
+    local content="$1"
+    local prefix="${2:-${DIM}│${RESET}}"
+
+    # Print each line with the prefix
+    while IFS= read -r line; do
+        printf "%s %s\n" "$prefix" "$line"
+    done <<< "$content"
+}
+
+print_user_input_box() {
+    local input="$1"
+    print_user_message_start
+    print_chat_content "$input" "${GREEN}│${RESET}"
+    print_user_message_end
+}
+
+print_agent_response_box() {
+    local agent="$1"
+    local response="$2"
+    print_agent_response_start "$agent"
+    print_chat_content "$response" "${CYAN}│${RESET}"
+    print_agent_response_end
+}
+
 # =============================================================================
 # MESSAGES
 # =============================================================================
 
 print_task() {
     local task="$1"
-    echo
-    echo "${BOLD}Task:${RESET} ${CYAN}\"$task\"${RESET}"
-    echo
+    print_user_message_start
+    printf "${GREEN}│${RESET} ${BOLD}Task:${RESET} %s\n" "$task"
+    print_user_message_end
 }
 
 print_orchestrator_message() {
     local message="$1"
-    echo "${MAGENTA}[Orchestrator]${RESET} $message"
+    print_agent_response_start "Orchestrator"
+    print_chat_content "$message" "${MAGENTA}│${RESET}"
+    print_agent_response_end
 }
 
 print_agent_message() {
     local agent="$1"
     local message="$2"
-    echo "${CYAN}[$agent]${RESET} $message"
+    print_agent_response_start "$agent"
+    print_chat_content "$message" "${CYAN}│${RESET}"
+    print_agent_response_end
 }
 
 print_user_prompt() {
-    printf "\n${GREEN}You:${RESET} "
+    echo
+    printf "${GREEN}╭─ You ────────────────────────────────────────────────${RESET}\n"
+    printf "${GREEN}│${RESET} "
 }
 
 print_focus_prompt() {
     local agent="$1"
-    printf "\n${CYAN}[$agent]${RESET} ${GREEN}You:${RESET} "
+    echo
+    printf "${CYAN}╭─ ${BOLD}$agent${RESET}${CYAN} (focused) ──────────────────────────────────${RESET}\n"
+    printf "${CYAN}│${RESET} "
 }
 
 print_task_assignment() {
     local agent="$1"
     local task="$2"
-    echo "  ${DIM}→${RESET} ${BOLD}$agent:${RESET} $task"
+    echo "${CYAN}│${RESET}   ${DIM}→${RESET} ${BOLD}$agent:${RESET} $task"
+}
+
+print_thinking() {
+    local message="${1:-Thinking...}"
+    printf "${DIM}│ %s${RESET}\n" "$message"
 }
 
 # =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentk8",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Multi-Agent Claude Code Terminal Suite - Orchestrate multiple Claude agents for software development and ML research",
   "keywords": [
     "claude",