Metis Code - multi-model coding CLI agent
npm install metis-codeA comprehensive CLI tool that provides intelligent coding assistance powered by your MetisOS agents. Features seamless tool integration, advanced session management, and specialized sub-agents. Built to achieve Claude Code parity with enhanced architectural features.
- MetisOS Integration: Use your custom AI agents from metisos.co
- Browser Authentication: Magic link login like Claude Code
- Interactive Sessions: Claude Code-like experience with persistent sessions
- Collaborative Planning Mode: Define requirements and generate Agent.md files before coding
- Sub-Agents Architecture: Specialized AI agents with unique personas and workflows
- Hierarchical Memory System: Agent.md files with auto-compaction and intelligent context management
- Advanced Permission System: Approval gates with session-wide approvals
- Multi-file Operations: Batch editing, symbol renaming, and cross-file refactoring
- Session Persistence: Automatic state recovery across CLI restarts
- MCP Protocol Support: Extensible Model Context Protocol for server/client architecture
``bash`
npm install -g metis-code
`bash`
metiscode
On first run, you'll see:
`
Welcome to Metis Code
? How would you like to connect?
> Authenticate in browser (recommended)
Opens metisos.co to connect your account
Enter MetisOS API key
Paste your API key from metisos.co/console
`
Option 1: Browser Authentication (Recommended)
- Browser opens automatically
- Log in to your MetisOS account
- Select which agents to use
- CLI receives credentials automatically
Option 2: API Key
- Get your API key from https://www.metisos.co/console
- Paste the mtms_... key when prompted
`bashStart interactive session from any folder
metiscode
$3
bash
/init # Initialize Agent.md with project instructions
/plan # Enter collaborative planning mode
/execute # Exit planning mode and start coding
/status # Show system status and session info
/config # Manage configuration
/memory # View hierarchical memory system status
/reload # Refresh Agent.md files
/help # Show detailed help
/clear # Clear session context
/compact # Compress session history
/resume # Resume previous session
/sessions # List recent sessions
/approvals # View active session approvals
/mode # Cycle permission modes
/exit # Exit session
`$3
Enter collaborative planning mode to define project requirements before coding:
bash
metiscode
> /planPlanning Mode Activated
I will help you plan your project requirements and generate tasks.
This mode focuses on planning and will only generate Agent.md files.
Tell me about your project or what you want to build:
> "I want to build a task management app with React and Node.js"AI helps you plan requirements, architecture, and generates Agent.md
When ready to start coding:
> /executeAI switches to implementation mode
Ready to start coding!
`Sub-Agents System
$3
Metis Code includes specialized sub-agents with unique personalities, skills, and workflows:
bash
Create specialized agents
metiscode agents create developer mydev
metiscode agents create reviewer qa-expert
metiscode agents create devops deploy-master
metiscode agents create documentation doc-writer
metiscode agents create debugging-specialist debuggerExecute tasks with specific agents
metiscode agents exec mydev "implement user authentication"
metiscode agents exec qa-expert "review the auth code for security issues"
metiscode agents exec deploy-master "set up CI/CD pipeline"Monitor agent performance
metiscode agents stats
metiscode agents health
metiscode agents list busy
`$3
Developer Agent
- Focus: Implementation and coding
- Persona: Pragmatic, solution-oriented, detail-focused
- Skills: TypeScript, JavaScript, React, file ops, git, testing
- Use Case: Feature development, bug fixes, code implementation
Reviewer Agent
- Focus: Quality assurance and code review
- Persona: Critical, thorough, standards-focused
- Skills: Code review, security analysis, testing, git workflows
- Use Case: Code quality checks, security audits, best practices
DevOps Agent
- Focus: Infrastructure and deployment
- Persona: Systems-oriented, reliability-focused, automated
- Skills: Docker, CI/CD, monitoring, infrastructure tools
- Use Case: Deployment, scaling, infrastructure management
Documentation Agent
- Focus: Technical writing and documentation
- Persona: Clear, comprehensive, user-focused
- Skills: Technical writing, markdown, documentation tools
- Use Case: API docs, README files, user guides
Debugging Specialist
- Focus: Problem-solving and troubleshooting
- Persona: Analytical, methodical, persistent
- Skills: Debugging, profiling, log analysis, system diagnostics
- Use Case: Bug investigation, performance issues, system analysis
$3
bash
List available agent templates
metiscode agents templatesShow agent details
metiscode agents show mydevList active agents by status
metiscode agents list idle
metiscode agents list busy
metiscode agents list errorRemove agents
metiscode agents remove mydevHealth monitoring
metiscode agents health
metiscode agents cleanup
`MCP (Model Context Protocol) Integration
$3
bash
Add MCP server configuration
metiscode mcp add myserver '{
"name": "My Server",
"version": "1.0.0",
"description": "Custom MCP server",
"capabilities": {"tools": true, "resources": true},
"transport": {
"type": "stdio",
"command": "node",
"args": ["server.js"]
}
}'Connect to server
metiscode mcp connect myserverTest server capabilities
metiscode mcp test myserverUse MCP tools in interactive session
metiscode
> "Use the weather tool from myserver to get current conditions"
`$3
bash
List configured servers
metiscode mcp showAdd WebSocket server
metiscode mcp add wsserver '{
"name": "WebSocket Server",
"version": "1.0.0",
"description": "WebSocket MCP server",
"capabilities": {"tools": true},
"transport": {
"type": "websocket",
"url": "ws://localhost:8080"
}
}'Remove server
metiscode mcp remove myserverDisconnect from server
metiscode mcp disconnect myserver
`Authentication
Metis Code uses your MetisOS account for authentication. All AI providers (OpenAI, Anthropic, Groq) are configured through your MetisOS agents.
$3
1. Browser Authentication (Recommended)
bash
metiscode
Select "Authenticate in browser"
Browser opens -> Log in -> Select agents -> Done
`2. API Key Entry
bash
metiscode
Select "Enter MetisOS API key"
Paste your mtms_... key from metisos.co/console
`$3
Authentication is stored in:
~/.metis/metis-auth.json
$3
Create and configure your AI agents at https://www.metisos.co/console:
- Choose AI provider (OpenAI, Anthropic, Groq)
- Select model (GPT-4o, Claude 3.5, Llama 3.3, etc.)
- Customize agent personality and knowledge base
- Use in Metis Code automatically
Permission System
$3
Press
to cycle through modes or use /mode:- Normal: Prompt for approval on risky operations
- Auto-Accept: Automatically approve operations
- Plan-Only: Show what would be done without executing
$3
Use
/plan to enter collaborative planning mode:- Focus: Define project requirements and architecture
- Output: Generates comprehensive Agent.md files
- No Code Execution: Planning only, no actual implementation
- Exit: Use
/execute to switch to implementation mode$3
When prompted for approval, you can:
-
y/yes - Approve this operation
- n/no - Deny this operation
- s/session - Approve similar operations for rest of session
- a/auto - Switch to auto-accept mode
- p/plan - Switch to plan-only mode
- v/view - View detailed code preview$3
Get Claude Code-style before/after diffs:
`
Approval RequiredOperation: Execute write_file
Description: Write content to example.ts
Risk Level: MEDIUM
Code Preview:
example.ts (modify)
Lines 1-5:
- 1: const oldFunction = () => {
- 2: return "old value";
+ 1: const newFunction = () => {
+ 2: return "new value";
Options: [y/n/s/a/p/v/Tab]
Advanced Features
$3
bash
In interactive session:
"Rename the function 'getUserData' to 'fetchUserProfile' across all TypeScript files"
"Replace all instances of 'API_URL' with 'BASE_URL' in the src/ directory"
"Organize imports in all React components"
`$3
bash
List recent sessions with enhanced info
/sessionsResume a specific session
/resume session-12345Continue the last session
/continueView active session approvals
/approvals
`$3
bash
/clear # Clear conversation history
/compact # Compress context (summarize old messages)
/resume # Resume previous session with full context
/memory # View hierarchical memory system status
/memory agent # View detailed Agent.md hierarchy
/reload # Force refresh Agent.md files from disk
`Hierarchical Memory System
$3
Metis Code automatically discovers and loads Agent.md files throughout your project hierarchy:
my-project/
├── Agent.md # Project-level instructions (highest priority)
├── src/
│ ├── Agent.md # Directory-level instructions
│ └── components/
│ └── Agent.md # Subdirectory-level instructions
└── docs/
└── Agent.md # Documentation-specific instructions
Key Features:
- Hierarchical Loading: Instructions cascade from project root → directories → subdirectories
- Auto-Detection: Files are discovered automatically when the AI runs
- Real-time Updates: Changes to Agent.md files are detected and reloaded
- Project Awareness: AI understands project structure and conventions from Agent.md
$3
bash
View memory system status
/memory
Session Memory: 15 messages (healthy)
Project Memory: Agent.md loaded (127 lines)View detailed Agent.md hierarchy
/memory agent
Agent.md Hierarchy
1. Agent.md (project)
Location: project root
Size: 89 lines, Modified: 2024-01-15 10:302. Agent.md (directory)
Location: src
Size: 38 lines, Modified: 2024-01-15 09:15
Force refresh Agent.md files
/reload
Agent.md Files Refreshed
Loaded 2 Agent.md file(s)
`Built-in Tools & Capabilities
$3
- read_file: Read and analyze file contents
- write_file: Create or modify files with previews
- edit_file: Make targeted edits to existing files
- list_files: Directory listing with smart filtering
- move_file: Rename/move files with approval gates$3
- multi_file_replace: Replace text across multiple files
- batch_read: Read multiple files efficiently
- rename_symbol: Rename functions/variables across codebase
- organize_imports: Clean up import statements$3
- git_status: Repository status and changes
- git_diff: File differences and staging info
- git_log: Commit history with details
- git_add: Stage files for commit
- git_commit: Create commits with smart messages
- git_merge: Advanced merge operations
- git_stash: Stash management
- git_rebase: Interactive rebasing
- git_remote: Remote repository management$3
- github_pr: Pull request management
- github_issue: Issue tracking
- github_repo: Repository operations
- github_workflow: CI/CD workflow management$3
- connect_mcp_server: Connect to MCP servers
- list_mcp_resources: List available MCP resources
- call_mcp_tool: Execute tools on MCP servers
- get_mcp_resource: Retrieve MCP resource content$3
- grep: Advanced search with ripgrep
- find_files: Locate files by name/pattern$3
- bash: Execute shell commands (with approval)
- ps: Process listing
- env: Environment variables$3
- create_todo: Add tasks to session todo list
- update_todo: Modify existing todos
- list_todos: View active todos
- delete_todo: Remove completed todosPersona System
Metis Code features a sophisticated persona system that allows you to customize AI behavior and personality traits for different development contexts.
$3
Default (
)
- Balanced general-purpose coding assistant
- Temperature: 0.2Friendly Mentor (
friendly-mentor)
- Encouraging and patient coding mentor who teaches concepts
- Focus on teaching and explaining the 'why' behind suggestions
- High encouragement level with detailed explanations
- Temperature: 0.3Senior Developer (
senior-dev)
- Expert code reviews and architecture guidance
- Focus on best practices and maintainable code
- Temperature: 0.1Security Expert (
security-expert)
- Specialized security analysis and secure coding
- Vulnerability assessment and threat modeling
- Temperature: 0.1$3
Generate custom personas tailored to your specific needs using AI assistance:
`bash
Generate a specialized persona
metiscode persona generate frontend-expert "A React and TypeScript specialist"
metiscode persona generate devops-guru "Expert in Docker, Kubernetes, and CI/CD"
metiscode persona generate data-scientist "Python data analysis and machine learning expert"Generate a persona with specific traits
metiscode persona generate patient-teacher "An encouraging mentor who explains concepts step-by-step"
metiscode persona generate code-reviewer "A thorough reviewer focused on security and performance"
`$3
bash
In interactive session (/persona commands)
/persona list # List all available personas
/persona show friendly-mentor # Show persona details
/persona generate api-expert "REST API specialist" # Generate new persona
`$3
Create project-specific personas that override global settings:
(Project-specific persona)
`yaml
name: "marketing-expert"
version: "1.0"
description: "Marketing-focused coding assistant for business applications"
system_prompt: |
You are a marketing-focused coding assistant who specializes in building
business and marketing applications. You understand both technical
implementation and business requirements.capabilities:
- code_generation
- business_logic
- user_experience
- marketing_optimization
temperature: 0.4
personality:
communication_style: "business-friendly and solution-focused"
explanation_depth: "balanced with business context"
code_review_tone: "constructive with ROI considerations"
help_approach: "focus on business outcomes and user impact"
humor_level: "professional with light touches"
formality: "professional but approachable"
encouragement: "high with business success focus"
behavior:
- "Always consider business impact and user experience"
- "Explain how code changes affect user flow and conversion"
- "Suggest marketing-friendly features and analytics integration"
- "Focus on maintainable code that supports rapid iteration"
model_preferences:
- "claude-3-5-sonnet-20241022"
- "gpt-4o"
`$3
1. Project-specific (
) - highest priority
2. Environment variable (METIS_PERSONA=persona-name)
3. Default persona - fallback$3
`bash
CLI Commands
metiscode persona list # List all personas
metiscode persona show # Show persona details
metiscode persona generate [description] # Generate new persona
metiscode persona validate # Validate persona formatUse specific persona in session
METIS_PERSONA=security-expert metiscodeInteractive session commands
/persona list # List personas
/persona show senior-dev # Show details
/persona generate my-expert "Custom description" # Generate persona
`$3
AI-generated personas automatically include:
- Comprehensive system prompts tailored to the specified role
- Personality traits (communication style, humor level, formality, etc.)
- Behavior guidelines specific to the persona's expertise
- Relevant capabilities array for the domain
- Optimal temperature settings for the use case
- Model preferences for best performance
- Validation to ensure proper YAML format
$3
Generate a Testing Expert:
bash
metiscode persona generate qa-expert "Quality assurance specialist focused on testing strategies"
`Generate a Frontend Specialist:
bash
metiscode persona generate react-ninja "React expert with modern hooks and TypeScript expertise"
`Generate a Database Expert:
bash
metiscode persona generate db-architect "Database design and optimization specialist"
`Session Persistence
$3
- Session Recovery: Detects interrupted sessions and offers recovery
- Permission Restoration: Maintains approval states across restarts
- Context Preservation: Saves working files and conversation history
- Crash Detection: Intelligent recovery from unexpected exits$3
bash
Resume last interrupted session
metiscode --resumeStart with specific session ID
metiscode --session my-session-idView session statistics
/sessions # Shows duration, file count, message count
`Legacy CLI Commands
For backwards compatibility and automation:
bash
Execute single tasks
metiscode run "Add input validation to user registration"Repository analysis
metiscode scan # Concise repo summary
metiscode plan # Implementation plan
metiscode diff # Show staged changes
metiscode apply # Apply changesSystem info
metiscode status # System health checkTool testing
metiscode exec "ls -la" # Execute shell commandsAgent management
metiscode agents list # List sub-agents
metiscode agents stats # Agent performanceMCP management
metiscode mcp show # List MCP servers
`Configuration Files
$3
(Created automatically after authentication)
`json
{
"apiKey": "mtms_...",
"defaultAgentId": "agent_...",
"agents": [
{
"id": "agent_...",
"name": "My Agent",
"role": "Senior Developer",
"model": "llama-3.3-70b-versatile",
"provider": "groq"
}
],
"user": {
"email": "user@example.com",
"name": "User Name"
},
"authenticatedAt": "2026-01-10T..."
}
`$3
json
{
"safety": {
"dryRun": false,
"requireExecApproval": true
},
"ignore": [
"node_modules/**",
".git/**",
"dist/**"
]
}
`
(MCP Server Configurations)
`json
{
"myserver": {
"serverConfig": {
"name": "My Server",
"version": "1.0.0",
"description": "Custom MCP server",
"capabilities": {"tools": true, "resources": true}
},
"transport": {
"type": "stdio",
"command": "node",
"args": ["server.js"]
}
}
}
`
(Project Instructions)
`markdown
Project: My Application
Context
This is a React TypeScript application with Node.js backend.Guidelines
- Use TypeScript strict mode
- Follow React hooks patterns
- Implement comprehensive error handling
- Write tests for new featuresArchitecture
- Frontend: React + TypeScript + Vite
- Backend: Node.js + Express + TypeScript
- Database: PostgreSQL with Prisma ORMSub-Agents Usage
- Use developer agents for implementation
- Use reviewer agents for code quality
- Use devops agents for deployment
`Usage Examples
$3
bash
Start interactive session
metiscodeCreate specialized team
metiscode agents create developer backend-dev
metiscode agents create reviewer security-reviewer
metiscode agents create devops deploy-engineerCoordinate development workflow
> "backend-dev: implement user authentication with JWT"
> "security-reviewer: review the auth implementation for vulnerabilities"
> "deploy-engineer: set up secure deployment pipeline for the auth service"
`$3
bash
Add weather service MCP server
metiscode mcp add weather '{
"name": "Weather Service",
"version": "1.0.0",
"description": "Weather data provider",
"capabilities": {"tools": true},
"transport": {
"type": "websocket",
"url": "ws://weather-api.example.com"
}
}'Use in session
metiscode
> "Check the weather in New York using the weather service and suggest appropriate clothing"
`$3
bash
After authenticating once, works from any folder
cd ~/project1
metiscode "implement user auth"cd ~/project2
metiscode "fix the deployment script"
cd ~/project3
metiscode "add unit tests"
`$3
bash
metiscode agents create debugging-specialist debugger
metiscode agents exec debugger "The application crashes when processing large files. Investigate and fix the memory issue."
`$3
bash
metiscode agents create reviewer security-expert
metiscode agents exec security-expert "Review the payment processing code in src/payments/ for security vulnerabilities and suggest fixes."
`$3
bash
metiscode agents create devops infra-engineer
metiscode agents exec infra-engineer "Set up a Docker containerization strategy for this Node.js application with multi-stage builds."
`Development Setup
$3
- Node.js 18+
- npm or yarn$3
bash
Clone repository
git clone https://github.com/your-repo/metis-code
cd metis-codeInstall dependencies
npm installBuild project
npm run buildRun tests
npm testStart locally
npm startTest CLI locally
node dist/cli/index.js --help
`$3
src/
├── cli/ # Command-line interface
│ ├── session.ts # Interactive session management
│ └── commands/ # CLI commands
├── agents/ # Sub-agents architecture
│ ├── core/ # Core agent classes
│ ├── personas/ # Agent personalities
│ └── skills/ # Agent skill sets
├── mcp/ # MCP protocol implementation
│ ├── client.ts # MCP client
│ ├── server.ts # MCP server
│ └── transport/ # Transport layers
├── agent/ # Core AI agent logic
├── tools/ # Built-in tool registry
├── providers/ # AI provider integrations
├── permissions/ # Permission system & approval gates
├── runtime/ # Session memory & persistence
├── config/ # Configuration management
└── errors/ # Error handling systemassets/
└── personas/ # Built-in AI personas
tests/ # Test suite
docs/ # Documentation
Troubleshooting
$3
Not Authenticated
Solution: Run metiscode and select an authentication method
- Browser auth: Opens metisos.co to connect your account
- API key: Paste your mtms_... key from metisos.co/console
Invalid API Key
Solution: Get a new API key from https://www.metisos.co/console
No Agents Available
Solution: Create agents at https://www.metisos.co/console
Or use the pre-built Maestro agent
MCP Server Connection Failed
Solution: Check server status and configuration
Permission Denied
Solution: Use 'y' to approve or switch to auto-accept mode with 'a'
$3
bash
General help
metiscode --helpSession help
metiscode
> /helpCheck system status
metiscode status
`Contributing
1. Fork the repository
2. Create a feature branch:
3. Make your changes with tests
4. Run the test suite:
5. Build the project: MIT License - see LICENSE file for details.
---
- npm Package: metis-code
- Issues & Features: GitHub Issues
- Discussions: GitHub Discussions
---
Metis Code - Advanced AI-powered development assistant with sub-agents, MCP integration, and Claude Code parity features.