hello-dave

Table of Contents

• Description
• Features
• Folder Structure
• Installation
• Usage
• Usage Examples
• Development
• Contributing
• License

Description

hello-dave is an ESM (ECMAScript Modules) toolkit for building AI agents with unified access to endpoints from Grok (xAI), OpenAI, and Anthropic. It provides CLI tools for interacting with agents locally or via WebSocket servers, along with pre-built agent scripts for various tasks like code generation, documentation, testing, and more.

The project emphasizes modular agent management, tool integration (e.g., web search, file operations), and session handling with memory and caching. With v0.0.8, enhanced portability allows spawning agents in isolated environments like /tmp while maintaining tool functionality relative to the current working directory (CWD).

Features

• Unified API Access: Seamless integration with xAI (Grok), OpenAI, and Anthropic models.
• CLI Tools: dave for querying agents, agentDave for spawning servers, codeDave for code servers.
• Agent Scripts: Specialized agents for code, docs, npm, todo, readme, memory, and more.
• WebSocket Support: Connect to remote agent servers for interactive or one-shot interactions.
• Toolsets: Built-in tools for search, file I/O, email, and custom toolcalls.
• Music Toolsets: Dedicated Stability AI (Stable Audio 3) and Minimax (Music 2.6/Cover) toolsets for text-to-music, audio transformation, inpainting, covers, lyrics, and more. See docs/music-toolsets.md for full details, tools, and agent examples.
• Session Management: Cache history, search sessions, reset, and inspect logs.
• ESM-First: Modern Node.js modules with TypeScript definitions.
• Portable Agent Spawning: spawn_agent.js enables creating and deploying agents anywhere (project dirs or fresh /tmp). Supports auto-deploy in existing projects (detects ./agents/*.js), manual code+bash in isolated setups. Tools adapt to CWD for portability. Hybrid modes combine server/client for chaining. See docs/prompt/spawn_agent.md for blueprint and validation.
• Multi-Agent Clusters: PM2-powered CodeServer for scalable, clustered agent deployments (e.g., code_agent + todo_agent). Defaults to port 9000/secret '123'. See docs/multi-agent-clusters.md for configuration.

Folder Structure

• bin/: Executables for CLI tools.

  • dave.js: Main CLI for asking agents or connecting to WebSocket servers.
  • spawn_agent.js: Spawns agent instances (binary: agentDave).
  • codeDave: Launches code servers (via PM2 clusters). References docs/multi-agent-clusters.md for setup and scaling.

• agents/: Agent scripts (*_agent.js) for specific tasks. These can be run directly with node agents/<script>.js.

  • ask_agent.js: General query agent.
  • code_agent.js: Code generation and execution agent (serves as main server in code clusters).
  • daisy_agent.js: Specialized agent (details in script).
  • docs_agent.js: Documentation-focused agent.
  • gpt_agent.js: OpenAI GPT integration agent.
  • grok_agent.js: xAI Grok-specific agent.
  • memory_agent.js: Agent with enhanced memory and context handling.
  • npm_agent.js: NPM package management agent.
  • prompt_agent.js: Prompt engineering and testing agent.
  • readme_agent.js: README.md management agent.
  • spawn_agent.js: Agent spawner (also in bin/). Creates portable CLI/WS agents + PM2 launchers. Validates/tests/deploys to ./agents/<name>.js. Supports hybrid server/client modes. Portable to /tmp (tools follow CWD). Blueprint: docs/prompt/spawn_agent.md.
  • test_agent.js: Testing and validation agent.
  • todo_agent.js: TODO list and task management agent.
  • codeserver.sh: Shell script for launching PM2-based code server clusters (uses agents above). See docs/multi-agent-clusters.md.

• lib/: Core library modules (e.g., index.js, wsCli.js, wsIO.js, API integrations).

• scenarios/: Test and example scenarios (e.g., toolset tests, integration scripts).

• types/: TypeScript definitions.

• utils/: Utility scripts (e.g., session management, testing).

• docs/: Additional documentation, including agent blueprints (e.g., prompt/spawn_agent.md) and multi-agent guides (e.g., multi-agent-clusters.md).

  • New: music-toolsets.md — Documentation for Stability and Minimax MusicToolsets with usage examples from agents/stability.js and agents/minimax.js.

• release/: Build artifacts.

Other files: package.json, CHANGELOG.md, TODO.md, LICENSE.

Installation

1. Prerequisites: Node.js >= 20. PM2 for multi-agent clusters: npm install -g pm2.

2. Local Development:

   git clone https://codeberg.org/duin/hello-dave.git
   cd hello-dave
   npm install

3. Global CLI Installation (for dave, agentDave, codeDave):

   npm install -g .
   # Or link for dev: npm run link-self

4. API Keys: Set environment variables (e.g., XAIKEY for xAI, OPENAI_API_KEY for OpenAI).

Usage

CLI Tools

• dave: Interact with agents locally or remotely.

  • Local query: dave --ask "Predict the weather"
  • One-shot remote: echo "Hello" | dave --connect 'ws://127.0.0.1:8080' --secret '123'
  • Interactive remote: dave --connect 'ws://127.0.0.1:8080' --secret '123'
  • Other: dave --list (sessions), dave --clear (cache), dave --help.

• agentDave: Spawn an agent server (powered by spawn_agent.js).

  agentDave --serve 8080 --secret '123'  # Starts WebSocket server

• codeDave: Launch a PM2 code server cluster.

  codeDave 8080 --secret '123'  # Or: dave --code 8080 --secret '123'

Running Agents

Run agent scripts directly:

node agents/spawn_agent.js --serve 8080 --secret '123'  # Spawn server
node agents/code_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'  # Client mode

For full options, see script headers or run with --help.

Programmatic Usage

Import and use in your Node.js app:

import { AgentManager } from '@j-o-r/hello-dave';
// Setup and run agent...

spawn_agent.js Specifics (v0.0.8 Portability Ready)

spawn_agent.js (executable as agentDave) creates and deploys portable agents in CLI, WebSocket server, client, or hybrid modes (server + client for tool chaining). It fetches live prompts from docs/prompt/spawn_agent.md and validates new agents via blueprint (temp files, syntax checks, grep for modes/tools).

• Modes:

  • Direct (One-Shot): Positional input, e.g., node agents/spawn_agent.js "Create a tester".
  • Interactive CLI: No input; runs REPL-like session.
  • Server: --serve <port> – Exposes as remote tool (e.g., for other agents to call spawn_agent).
  • Client: --connect <ws_url> – Connects to remote server for tool access.
  • Hybrid: --serve <port> --connect <ws_url> – Serves locally while using remote tools.

• Portability:

  • In Project: Auto-deploys to ./agents/<name>.js if ./agents/*.js exist (uses existing structure).
  • Fresh /tmp: Manual code generation + bash setup (e.g., mkdir /tmp/myproj/agents; cd /tmp/myproj; node spawn_agent.js ...). Tools (e.g., read_file) follow CWD, ensuring isolation without fixed paths.
  • Works in any dir; no repo deps beyond Node.js + npm installs.

• Custom Tools: Specify in prompt, e.g., "name=coderev, tools=read_file,web_search,execute_bash_script".

For validation/testing: See blueprint in docs/prompt/spawn_agent.md (includes bash examples like node agents/NEW_AGENT.js --help or server connect tests).

CodeServer & PM2 Multi-Agent (v0.0.8)

CodeServer (via bin/codeDave or agents/codeserver.sh) launches scalable, PM2-clustered multi-agent environments for collaborative tasks (e.g., code generation + task management). It deploys agents like code_agent, todo_agent, and readme_agent on a WebSocket server, enabling chaining and load balancing.

• Defaults: Port 9000, secret '123' (customizable via args).

• Prerequisites: Install PM2 globally (npm install -g pm2).

• Quickstart:

  codeDave 9000 --secret 123  # Launches PM2 cluster on ws://127.0.0.1:9000/ws
  pm2 list  # Verify processes (e.g., code_agent, todo_agent instances)
  echo "task" | bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123  # One-shot query to cluster

  This starts the cluster, lists running agents, and sends a test task (response routed to available agents).

• Scaling & Management: Use PM2 commands (e.g., pm2 scale <app> 4, pm2 stop all). For ecosystem config, PM2 JSON files, or agent orchestration, see the full guide in docs/multi-agent-clusters.md.

• Integration: Combine with spawn_agent.js for dynamic agent addition to clusters (e.g., spawn new agents and connect via --connect ws://127.0.0.1:9000/ws).

Usage Examples

• Direct Spawn (Project):

  cd hello-dave  # Or any project with ./agents/
  node agents/spawn_agent.js "Create code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file,execute_bash_script,web_search"
  # Deploys to ./agents/coderev_agent.js; test: node agents/coderev_agent.js "Review this diff"

• /tmp Workflow (Portable, Fresh Setup):

  mkdir -p /tmp/myportable/agents
  cd /tmp/myportable
  # Copy or fetch spawn_agent.js (e.g., curl from repo or npm install @j-o-r/hello-dave)
  npm init -y && npm i @j-o-r/hello-dave @j-o-r/sh
  node spawn_agent.js "Create todo agent: name=todo, desc=Task manager, tools=read_file,write_file"
  # Deploys to ./agents/todo_agent.js; tools use /tmp/myportable as CWD
  node agents/todo_agent.js --serve 8081 --secret abc  # Test server mode

• Hybrid Mode with Custom Tools:

  node agents/spawn_agent.js --serve 8081 --connect ws://127.0.0.1:8080/ws --secret abc "Spawn a docs agent with custom email tool"
  # Serves on 8081 (exposes new agent), connects to 8080 (gains remote tools like email)
  # Test: In another term, node agents/spawn_agent.js --connect ws://127.0.0.1:8081/ws --secret abc "Use the new docs agent"

• Spawn a Server:

  node agents/spawn_agent.js --serve 8080 --secret '123'
  # Then connect: echo "Task" | dave --connect 'ws://127.0.0.1:8080' --secret '123'

• Launch Code Cluster (includes multiple agents):

  node agents/codeserver.sh 9000 '123'  # Or use codeDave 9000 --secret 123
  # Connects code_agent, todo_agent, readme_agent, etc., to the server on ws://127.0.0.1:9000/ws.
  # Test: pm2 list; echo "Optimize this code" | dave --connect ws://127.0.0.1:9000/ws --secret 123
  # For advanced config: See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).

• Local Agent Query (no server):

  dave --ask --model 'grok-4-1-fast-reasoning' "Write a function"

• Custom Agent:

  node agents/docs_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'

See scenarios/ for more test scenarios.

Development

• Build Types: npm run types
• Test: npm run tests (runs utils/test.sh)
• Release: npm run release then npm run publish
• Local Linking: npm run link-self / npm run unlink-self

Use git status and ls to inspect changes. Ensure ESM compatibility.

Contributing

Contributions welcome! Fork the repo, create a branch, and submit a pull request to https://codeberg.org/duin/hello-dave.

• Report bugs: https://codeberg.org/duin/hello-dave/issues
• Follow Apache-2.0 license.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Repository: https://codeberg.org/duin/hello-dave