commit c01ce454b1b57569f7f207c2b66e0f33558f8666
parent cc16f827e737f981fce5d28a4b28e646115327dd
Author: William Casarin <jb55@jb55.com>
Date: Mon, 9 Feb 2026 11:02:10 -0800
docs(dave): update README with agentium branch features
Document all new features from the agentium branch including:
- Dual AI modes (Chat vs Agentic)
- Multi-agent system with RTS-style scene view
- Focus queue with priority-based attention management
- Claude Code integration with interactive permissions
- Auto-accept rules for safe operations
- Keyboard-driven workflow with full shortcut table
- Session resume and discovery from ~/.claude/projects/
- IPC spawn for external agent creation
- New UI components (diff view, badges, pickers)
Diffstat:
1 file changed, 115 insertions(+), 24 deletions(-)
diff --git a/crates/notedeck_dave/README.md b/crates/notedeck_dave/README.md
@@ -1,70 +1,159 @@
# Dave - The Nostr AI Assistant
-Dave is an AI-powered assistant for the Nostr protocol, built as a Notedeck application. It provides a conversational interface that can search, analyze, and present Nostr notes to users.
+Dave is an AI-powered assistant for the Nostr protocol, built as a Notedeck application. It provides both a simple conversational interface for querying Nostr data and a full-featured agentic coding environment with Claude Code integration.
<img src="https://cdn.jb55.com/s/73ebab8f43804da8.png" width="50%"/>
## Overview
-Dave demonstrates how to build a feature-rich application on the Notedeck platform that interacts with Nostr content. It serves both as a useful tool for Nostr users and as a reference implementation for developers building Notedeck apps.
+Dave serves two purposes:
+
+1. **Nostr Assistant** - A conversational interface that can search, analyze, and present Nostr notes using natural language
+2. **Agentic IDE** - A multi-agent development environment with Claude Code integration for coding tasks
+
+You can use either mode depending on your needs—simple chat for quick Nostr queries, or agentic mode for software development workflows.
## Features
+### Core Features
+
- [x] Interactive 3D avatar with WebGPU rendering
- [x] Natural language conversations with AI
- [x] Query and search the local Nostr database for notes
- [x] Present and render notes to the user
- [x] Tool-based architecture for AI actions
+- [x] Multiple AI providers (OpenAI, Anthropic, Ollama)
- [ ] Context-aware searching (home, profile, or global scope)
-- [ ] Chat history persistence
- [ ] Anonymous [lmzap](https://jb55.com/lmzap) backend
+### AI Modes
+
+- **Chat Mode** - Simple OpenAI-style conversational interface for Nostr queries
+- **Agentic Mode** - Full IDE with permissions, sessions, scene view, and Claude Code integration
+
+### Multi-Agent System (Agentic Mode)
+
+- **RTS-Style Scene View** - Visual grid-based view for managing multiple agents simultaneously
+- **Focus Queue** - Priority-based system for agent attention (NeedsInput > Error > Done)
+- **Auto-Steal Focus** - Automatically cycle through agents requiring attention
+- **Session Management** - Multiple independent AI sessions with per-session working directories
+- **Subagent Support** - Track and display Task tool subagents within chat history
+
+### Claude Code Integration (Agentic Mode)
+
+- **Interactive Permissions** - Allow/Deny tool calls with diff view for file changes
+- **Auto-Accept Rules** - Configurable rules for automatically accepting safe operations:
+ - Small edits (2 lines or less by default)
+ - Read-only bash commands (grep, ls, cat, find, etc.)
+ - Cargo commands (build, check, test, fmt, clippy)
+- **Plan Mode** - Toggle plan mode with `Ctrl+M` for architectural planning
+- **Session Resume** - Resume previous Claude Code sessions from filesystem
+- **AskUserQuestion Support** - Answer multi-choice questions from the AI
+
+### Keyboard-Driven Workflow (Agentic Mode)
+
+| Shortcut | Action |
+|----------|--------|
+| `1` / `2` | Accept / Deny permission requests |
+| `Shift+1` / `Shift+2` | Accept / Deny with custom message |
+| `Escape` | Interrupt AI (double-press to confirm) |
+| `Ctrl+Tab` / `Ctrl+Shift+Tab` | Cycle through agents |
+| `Ctrl+1-9` | Jump to agent by number |
+| `Ctrl+T` | New agent |
+| `Ctrl+Shift+T` | Clone agent (same working directory) |
+| `Ctrl+N` / `Ctrl+P` | Focus queue navigation (higher/lower priority) |
+| `Ctrl+D` | Toggle Done status in focus queue |
+| `Ctrl+M` | Toggle plan mode |
+| `Ctrl+\` | Toggle auto-steal focus |
+| `Ctrl+G` | Open external editor for input |
+| `Ctrl+V` | Toggle scene view |
+| `Delete` | Delete selected agent |
+
+### UI Components
+
+- **Diff View** - Syntax-highlighted diff for Edit/Write tool permission requests
+- **Status Badges** - Visual indicators for plan mode, agent status, and keybinds
+- **Keybind Hints** - Contextual hints shown when Ctrl is held
+- **Directory Picker** - Select working directory when creating sessions
+- **Session Picker** - Resume existing Claude Code sessions
+- **Compaction Status** - Visual indicator when `/compact` is running
+
+### External Integration
+
+- **IPC Spawn** - Create agents from external tools via Unix domain socket
+- **`notedeck-spawn` CLI** - Spawn agents from terminal: `notedeck-spawn /path/to/project`
+
## Technical Details
Dave uses:
- Egui for UI rendering
-- WebGPU for 3D avatar visualization
-- OpenAI API (or Ollama with compatible models)
-- NostrDB for efficient note storage and querying
-- Async Rust for non-blocking API interactions
+- WebGPU for 3D avatar visualization (optional)
+- Claude Agent SDK for agentic workflows
+- OpenAI API / Anthropic API / Ollama for chat mode
+- NostrDB for Nostr note storage and querying
+- Tokio for async operations
+- Unix domain sockets for IPC
## Architecture
Dave is structured around several key components:
-1. **UI Layer** - Handles rendering and user interactions
+1. **UI Layer** - Handles rendering with scene view and chat panels
2. **Avatar** - 3D representation with WebGPU rendering
-3. **AI Client** - Connects to language models via OpenAI or Ollama
-4. **Tools System** - Provides structured ways for the AI to interact with Nostr data
-5. **Message Handler** - Manages conversation state and message processing
-
-## Usage as a Reference
-
-Dave serves as an excellent reference for developers looking to:
-
-- Build conversational interfaces in Notedeck
-- Implement 3D rendering with WebGPU in Rust applications
-- Create tool-based AI agents that can take actions in response to user requests
-- Query and present Nostr content in custom applications
+3. **Session Manager** - Manages multiple independent AI sessions
+4. **Focus Queue** - Priority-based attention system for multi-agent workflows
+5. **AI Backend** - Pluggable backends (Claude, OpenAI, Ollama)
+6. **Tools System** - Provides structured ways for the AI to interact with Nostr data
+7. **Auto-Accept Rules** - Configurable permission auto-approval
+8. **IPC Listener** - External spawn requests via Unix socket
+9. **Session Discovery** - Finds resumable Claude sessions from `~/.claude/projects/`
## Getting Started
+### Chat Mode (OpenAI/Ollama)
+
1. Clone the repository
-2. Set up your API keys for OpenAI or configure Ollama
+2. Set up your API keys:
```
export OPENAI_API_KEY=your_api_key_here
# or for Ollama
export OLLAMA_HOST=http://localhost:11434
```
-3. Build and run the Notedeck application with Dave
+3. Build and run Notedeck with Dave
+
+### Agentic Mode (Claude Code)
+
+1. Install Claude Code CLI: `npm install -g @anthropic-ai/claude-code`
+2. Authenticate: `claude login`
+3. Run Dave and select a working directory when creating a new agent
## Configuration
Dave can be configured to use different AI backends:
-- OpenAI API (default) - Set the `OPENAI_API_KEY` environment variable
-- Ollama - Use a compatible model like `hhao/qwen2.5-coder-tools` and set the `OLLAMA_HOST` environment variable
+- **OpenAI API** (Chat mode) - Set the `OPENAI_API_KEY` environment variable
+- **Anthropic Claude** (Chat mode) - Set the `ANTHROPIC_API_KEY` environment variable
+- **Ollama** (Chat mode) - Use a compatible model and set the `OLLAMA_HOST` environment variable
+- **Claude Code** (Agentic mode) - Requires Claude Code CLI installed and authenticated
+
+## File Locations
+
+- IPC Socket:
+ - Linux: `$XDG_RUNTIME_DIR/notedeck/spawn.sock`
+ - macOS: `~/Library/Application Support/notedeck/spawn.sock`
+- Claude Sessions: `~/.claude/projects/<project-path>/`
+
+## Usage as a Reference
+
+Dave serves as an excellent reference for developers looking to:
+
+- Build conversational interfaces in Notedeck
+- Implement 3D rendering with WebGPU in Rust applications
+- Create tool-based AI agents that can take actions in response to user requests
+- Query and present Nostr content in custom applications
+- Build multi-agent systems with priority-based focus management
+- Integrate Claude Code into custom applications
## Contributing
@@ -77,3 +166,5 @@ GPL
## Related Projects
- [nostrdb](https://github.com/damus-io/nostrdb) - Embedded database for Nostr notes
+- [Claude Code](https://claude.ai/claude-code) - Anthropic's agentic coding tool
+- [Claude Agent SDK](https://github.com/anthropics/claude-code) - SDK for Claude Code integration
