@higginsrob/local-ai
Advanced tools
A powerful CLI tool for orchestrating multi-agent AI conversations and managing specialized AI assistants powered by Docker AI Models and MCP (Model Context Protocol) tools.
Multi-Agent Collaboration: Create meeting rooms where multiple AI agents with different expertise collaborate on complex problems. Agents can communicate with each other, building on each other's responses to provide comprehensive solutions.
Agent-Based Architecture: Define specialized AI agents once, use them everywhere. Each agent has its own personality, expertise, and configuration.
Docker-Powered: Runs entirely on your local machine using Docker AI Models - no cloud services, no API keys, full privacy.
coder "prompt")npm install -g @higginsrob/local-ai
ai status
This checks your Node.js version, Docker availability, installed models, and MCP servers.
# Create a technical expert
ai agent new cto
# Configure with: ai/llama3.2:latest, "You are a CTO..."
# Create a business strategist
ai agent new ceo
# Configure with: ai/llama3.2:latest, "You are a CEO..."
# Create a financial expert
ai agent new cfo
# Configure with: ai/llama3.2:latest, "You are a CFO..."
ai meeting start executive-team ceo cto cfo
Now you can ask questions and the most qualified agent will respond, or agents will collaborate:
> We need to decide on our cloud infrastructure strategy
ceo: This is a critical decision. @cto what are the technical considerations?
cto: From a technical standpoint, we should consider scalability and cost...
@cfo what's our budget for infrastructure?
cfo: We can allocate $50K monthly for cloud services...
# Interactive mode with an agent
ai run coder
# Single execution
ai run coder "Explain how Docker works"
# Install as executable
ai agent install
coder "Help me write a React component"
# List all meeting rooms
ai meeting ls
# List all agents
ai agent ls
# Show meeting details
ai meeting show executive-team
ai meeting - Multi-Agent CollaborationManage and interact with multi-agent meeting rooms.
ai meeting start <room-name> <agent1> <agent2> [agent3...]
# Examples:
ai meeting start executive-team ceo cto cfo
ai meeting start project-planning pm dev designer
ai meeting start research-team analyst scientist writer
Requirements:
ai agent new)Meeting Features:
cto, what do you think? or use @cto anywhereai meeting ls
Shows all active meeting rooms with participants and message counts.
ai meeting show <room-name>
# Example:
ai meeting show executive-team
Displays participants, settings, metadata, and recent messages.
# List available archives
ai meeting restore
# Restore specific archive
ai meeting restore <archive-name>
Restores archived meeting sessions created with /clear command during meetings.
When in a meeting session, use these commands:
Response Management:
/respond <agent> - View buffered response from agent/buffered or /b - List all agents with buffered responsesMeeting Information:
/participants or /p - Show all participants/status or /s - Show meeting statistics/history [count] - Show recent messages (default: 10)/show <agent> - Display agent's full configuration and system promptAgent-to-Agent Controls:
/chain-length - View current max chain depth/chain-length <n> - Set max agent-to-agent conversation depth (0 to disable)Session Management:
/reset or /r - Clear meeting history (keeps participants)/clear or /c - Clear screen/quit or /q - Exit meetingSee docs/MEETING_COMMAND.md for comprehensive documentation.
ai run - Single Agent InteractionRun AI agent or model with a prompt or start interactive mode.
Using an Agent:
# Interactive mode with agent
ai run coder
# Single execution
ai run coder "What is TypeScript?"
# With options (override agent defaults)
ai run coder --temperature 0.9 --max-tokens 1024 --debug
Using a Model Directly:
# Interactive mode with model
ai run ai/llama3.2:latest
# Single execution
ai run ai/llama3.2:latest "What is TypeScript?"
Options:
--ctx-size <size> - Context window size (default: from agent or 4096)--max-tokens <tokens> - Maximum response tokens (default: from agent or 2048)--temperature <temp> - Temperature 0-2 (default: from agent or 0.7)--top-p <p> - Top P 0-1 (default: from agent or 0.9)--top-n <n> - Top N (default: from agent or 40)--debug - Show debug informationInteractive Mode Slash Commands:
/help - Show help for slash commands/status - Show performance metrics and context window usage/show - Display agent configuration and system prompt/compact - Summarize and compact session to reduce token usage/clear - Save current session to archive and start fresh/reset - Reset chat history (without archiving)/meeting <room-name> <agents...> - Switch to multi-agent meeting mode/ctx-size <size> - Set context window size/max-size <size> - Set max response size/temperature <float> - Set temperature/top_p <float> - Set top_p/top_n <int> - Set top_n/debug <bool> - Enable/disable debug mode/quit, /q, /exit - Exit interactive modeai agent - Manage AI AgentsCreate and manage specialized AI agent configurations.
# List all agents
ai agent ls
# Create new agent (interactive prompts)
ai agent new coder
# Show agent details
ai agent show coder
# Edit agent in your default editor
ai agent edit coder
# Remove agent
ai agent remove coder
# Configure agent settings (interactive)
ai agent configure coder
# Manage personality traits
ai agent traits coder # Multi-select interface with 100+ traits
ai agent trait-add coder # Add single trait with autocomplete
ai agent trait-remove coder # Remove single trait
# Manage expertise
ai agent expertise-add coder # Add area of expertise
ai agent expertise-remove coder # Remove area of expertise
# Manage custom attributes
ai agent attribute-add coder # Add custom key-value attribute
ai agent attribute-remove coder # Remove custom attribute
# Import/Export
ai agent export coder ./coder-agent.json
ai agent import ./coder-agent.json
# Install agents as executables
ai agent install
# Now you can run: coder "your prompt"
# Show current session performance status
ai agent status
# Compact a session to reduce context usage
ai agent compact <session-id>
Agent Personality Traits:
Choose from 100+ personality traits across three categories:
Traits are automatically included in the agent's system prompt.
ai profile - User ProfilesManage user profiles to personalize AI interactions.
# Show current profile
ai profile show
# Create new profile
ai profile new developer
# Select profile
ai profile select developer
# Edit in your default editor
ai profile edit
# Edit specific profile
ai profile edit developer
# Add attributes
ai profile add role "Senior Developer"
ai profile add expertise '["typescript","docker","ai"]'
ai profile add preferences '{"code_style": "functional"}'
# Remove attribute
ai profile remove role
# Import/Export
ai profile export ./my-profile.json
ai profile import ./my-profile.json
ai session - Session ManagementManage chat sessions for single-agent interactions.
# List all sessions
ai session ls
# Show session details
ai session show session-coder
# Open session in pager (less)
ai session open session-coder
# Remove last message(s)
ai session pop [count]
# Create new session
ai session new my-session
# Remove session
ai session remove session-coder
# Remove all sessions and meetings
ai session reset
# Import/Export
ai session export session-coder ./my-session.json
ai session import ./my-session.json
Note: Most users won't need to manage sessions manually. Sessions are created automatically when you run agents and meetings.
ai status - System StatusCheck installation and validate all dependencies.
ai status
Shows:
ai meeting start strategy-session ceo cto cfo
> What should be our top priorities for Q1?
ceo: We need to focus on three areas: market expansion, product quality,
and team growth. @cto what's our technical capacity for scaling?
cto: We can handle 2x growth with current infrastructure, but we'll need
to invest in automation. @cfo what's our budget situation?
cfo: We have $500K allocated for Q1. I recommend 40% for infrastructure,
40% for hiring, and 20% for marketing. @ceo does that align with
your strategy?
ceo: Perfect. Let's prioritize hiring first, then infrastructure...
ai meeting start design-review architect developer qa
> We need to design the authentication system
architect: I recommend OAuth2 with JWT tokens. @developer how would you
implement the token refresh flow?
developer: I'd use a sliding window approach with 15-min access tokens
and 7-day refresh tokens. @qa what are the security test cases
we should cover?
qa: We need to test token expiration, refresh flows, and logout scenarios...
ai meeting start research analyst scientist writer
> Analyze the impact of AI on software development
analyst: I'll gather the current market data and trends.
scientist: I can provide the technical research on AI capabilities.
writer: I'll synthesize both perspectives into a comprehensive report.
> Great! Analyst, please start with the market overview
analyst: Based on recent data, 78% of development teams are now using AI...
The system automatically enhances prompts with context from your agent and profile configurations:
When you interact with an AI model, the system builds a complete prompt:
[Your Agent's Base System Prompt]
# Agent Attributes
[Formatted attributes from agent config]
# User Attributes
[Formatted attributes from your profile]
[MEETING CONTEXT - if in a meeting]
[List of participants, their roles, @mention instructions, etc.]
{
"name": "coder",
"model": "ai/llama3.2:latest",
"systemPrompt": "You are an expert software developer.",
"modelParams": {
"ctxSize": 8192,
"maxTokens": 2048,
"temperature": 0.7
},
"attributes": {
"name": "Senior Developer",
"nickname": "Dev",
"expertise": ["typescript", "python", "docker"],
"personality": ["analytical", "thorough", "helpful"]
}
}
{
"name": "default",
"attributes": {
"name": "Rob Higgins",
"role": "Engineering Lead",
"expertise": ["architecture", "devops"],
"preferences": {
"code_style": "functional",
"documentation": "detailed"
}
}
}
This provides rich context to every AI interaction, making responses more personalized and relevant.
When sessions get too large and approach context limits:
# In interactive mode
/compact
# Or via command
ai agent compact session-coder
The system will:
Install agents as direct commands:
ai agent install
# Now run agents directly
coder "Write a React component for a todo list"
pm "Create a project timeline"
writer "Draft a blog post about AI"
Executables are created in ~/.local/bin/ and symlinked to your PATH.
Save important conversations:
# In a meeting or chat
/clear
# Later, list archives
ai meeting restore
# Restore specific conversation
ai meeting restore project-planning-2024-11-06
Archives preserve:
All data is stored in ~/.ai/:
~/.ai/
├── config.json # Global configuration
├── profiles/ # User profiles
│ └── default.json
├── agents/ # Agent configurations
│ ├── ceo.json
│ ├── cto.json
│ └── developer.json
├── sessions/ # Chat history (single-agent)
│ └── session-coder.json
├── meetings/ # Meeting room sessions
│ └── room-executive-team.json
├── archives/ # Archived conversations
│ └── project-planning-2024-11-06.json
└── bin/ # Agent executables
├── ceo
├── cto
└── developer
This tool uses Docker AI Models via llama.cpp HTTP endpoints.
ai/llama3.2:latest - Meta's Llama 3.2 (recommended)ai/mistral:latest - Mistral AIai/gemma:latest - Google Gemmaai/phi:latest - Microsoft Phiai/qwen:latest - Alibaba Qwenai/deepseek:latest - DeepSeek# Pull a model using Docker AI Models
docker model pull ai/llama3.2:latest
# List available models
docker model ls
# Check running models
docker model ps
# Models are automatically served via llama.cpp at:
# http://localhost:12434/engines/llama.cpp/v1/chat/completions
Different models have different characteristics:
Configure per agent in their configuration file.
Create a virtual dev team:
ai agent new architect # System design and architecture
ai agent new developer # Implementation and coding
ai agent new qa # Testing and quality assurance
ai agent new devops # Infrastructure and deployment
ai meeting start sprint-planning architect developer qa devops
Create a strategic team:
ai agent new ceo # Strategic direction
ai agent new cfo # Financial planning
ai agent new coo # Operations
ai agent new cmo # Marketing strategy
ai meeting start quarterly-review ceo cfo coo cmo
Create a content team:
ai agent new writer # Content writing
ai agent new editor # Editing and refinement
ai agent new researcher # Fact-checking and research
ai agent new seo # SEO optimization
ai meeting start blog-creation writer editor researcher seo
Create a learning team:
ai agent new teacher # Explains concepts
ai agent new tutor # Provides practice problems
ai agent new mentor # Career guidance
ai agent new reviewer # Reviews work
ai meeting start study-session teacher tutor mentor reviewer
# Clone repository
git clone https://github.com/higginsrob/ai.git
cd ai
# Install dependencies
npm install
# Run locally
node --experimental-strip-types src/index.ts status
# Or use the npm script
npm start status
# Link globally for testing
npm link
ai status
This project has comprehensive test coverage with 124 tests covering core functionality.
# Run all tests
npm test
# Run with coverage report
npm run test:coverage
# Type checking
npm run typecheck
Overall Coverage: ~20% with excellent coverage of critical business logic:
| Module | Coverage | Lines | Description |
|---|---|---|---|
| config.ts | 100% | ✅ All | Configuration management |
| prompt-builder.ts | 100% | ✅ All | Dynamic prompt generation |
| storage.ts | 87.86% | ✅ High | Data persistence & sessions |
| stream-handler.ts | 82.14% | ✅ High | Token streaming |
| meeting-interactive.ts | 25.39% | ✅ Core | Multi-agent coordination |
| slash-commands.ts | 30.88% | ✅ Core | Command handling |
What's Tested:
Test Suites:
✅ 124 tests passing
📦 30 test suites
🎯 Zero failing tests
⚡ ~190ms execution time
Lower coverage areas are CLI entry points that require integration testing with terminal I/O and user prompts. The core business logic has excellent coverage.
ai/
├── src/
│ ├── commands/ # CLI commands
│ │ ├── run.ts # Single agent execution
│ │ ├── meeting.ts # Multi-agent meetings
│ │ ├── agent.ts # Agent management
│ │ ├── profile.ts # Profile management
│ │ ├── session.ts # Session management
│ │ └── status.ts # System status
│ ├── lib/ # Core libraries
│ │ ├── interactive.ts # Single-agent interactive mode
│ │ ├── meeting-interactive.ts # Multi-agent mode
│ │ ├── slash-commands.ts # Single-agent commands
│ │ ├── meeting-slash-commands.ts # Meeting commands
│ │ ├── prompt-builder.ts # Dynamic prompt generation
│ │ ├── storage.ts # File-based storage
│ │ └── stream-handler.ts # Response streaming
│ ├── types/ # TypeScript types
│ │ ├── agent.ts
│ │ ├── meeting.ts
│ │ ├── session.ts
│ │ └── ...
│ └── data/
│ └── personality.json # 100+ personality traits
├── tests/ # Test files
├── docs/ # Documentation
│ ├── MEETING_COMMAND.md
│ ├── AGENT_WORKFLOW.md
│ └── ...
├── example/ # Example configurations
│ ├── ceo.json
│ ├── cto.json
│ └── ...
├── bin/ # Executable entry point
└── package.json
This project uses a dual TypeScript workflow:
--experimental-strip-types (no compilation needed)# Build for production
npm run build
# Clean build artifacts
npm run clean
See docs/DEVELOPMENT.md for details on the build process.
To create a new release, see the Release Process Guide.
Quick summary:
package.jsonCHANGELOG.mdmaingit tag -a v0.0.8 -m "Release notes"git push origin v0.0.8Contributions are welcome! Please:
git checkout -b feature/amazing-feature)npm test) - We maintain 100% pass ratenpm run test:coverage) to verify coverageTesting Guidelines:
Have an idea? Open an issue on GitHub!
Make sure you're using Node.js v23.6 or later:
node --version
If not, install the latest version from nodejs.org.
Start the Docker daemon:
# macOS/Linux
sudo systemctl start docker
# macOS with Docker Desktop
open -a Docker
Make sure you have Docker AI Models set up and models pulled:
# Check Docker AI Models
docker model ls
# Pull a model if needed
docker model pull ai/llama3.2:latest
# Check if models are running
docker model ps
# The endpoint should be available at:
# http://localhost:12434/engines/llama.cpp/v1/chat/completions
If you see "Agent is currently busy in another session":
# Find the process
ps aux | grep "ai meeting\|ai run"
# Kill the process
kill <pid>
# Or force unlock (in case of crashed session)
# The agent will auto-unlock after process termination
ai agent installTry installing to ~/.local/bin instead:
mkdir -p ~/.local/bin
ai agent install
Then add to your PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
If agents mention themselves (e.g., "@dev to @dev"):
# Check the agent's configuration
ai meeting show <agent-name>
# Verify the agent has proper attributes
ai agent show <agent-name>
# Add missing attributes
ai agent edit <agent-name>
Ensure each agent has at minimum:
name - Full namenickname - Short handle for @mentionsSee docs/SHOW_COMMAND.md for debugging techniques.
Q: Do I need API keys or cloud services?
A: No! Everything runs locally on your machine using Docker AI Models.
Q: How much RAM/CPU do I need?
A: Minimum 8GB RAM recommended. Performance scales with hardware. Smaller models (phi, gemma) work on 4GB.
Q: Can I use OpenAI or Anthropic models?
A: Not currently. This tool is designed for local Docker AI Models. Cloud integration may come in future releases.
Q: How many agents can be in a meeting?
A: Technically unlimited, but 3-5 agents is optimal for coherent conversations.
Q: Can agents see each other's messages?
A: Yes! All agents in a meeting share the same conversation history.
Q: How do I stop agents from talking too much to each other?
A: Use /chain-length 0 to disable agent-to-agent chaining, or set it to a low number like 2-3.
Q: Can I use this for production applications?
A: This is primarily a development and exploration tool. For production, consider additional error handling and monitoring.
Q: Is my data private?
A: Yes! Everything runs locally. No data is sent to external servers.
MIT License - see LICENSE file for details.
Rob Higgins
Happy Multi-Agent Collaborating! 🤖🤝🤖
FAQs
Local AI Agent Assistants Manager using Docker AI Models and MCP tools
We found that @higginsrob/local-ai demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Malicious packages published to npm, PyPI, Go Modules, crates.io, and Packagist impersonate developer tooling to fetch staged malware, steal credentials and wallets, and enable remote access.
Security News
Microsoft has released an open source toolkit for enforcing runtime security policies on AI agents as adoption accelerates faster than governance controls.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.