Metis Code - AI-Powered Development Assistant

A 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.

Key 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

Installation

npm install -g metis-code

Quick Start

1. First Run - Authenticate with MetisOS

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

2. Start Coding

# Start interactive session from any folder
metiscode

# Use natural language:
"Fix the authentication bug in login.ts"
"Create a React component for user profiles"
"Add error handling to the API endpoints"
"Refactor the database connection logic"

3. Slash Commands (In Interactive Session)

/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

4. Planning Mode

Enter collaborative planning mode to define project requirements before coding:

metiscode
> /plan

# Planning 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:
> /execute

# AI switches to implementation mode
# Ready to start coding!

Sub-Agents System

Specialized AI Agents

Metis Code includes specialized sub-agents with unique personalities, skills, and workflows:

# 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 debugger

# Execute 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

Available Agent Types

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

Agent Management

# List available agent templates
metiscode agents templates

# Show agent details
metiscode agents show mydev

# List active agents by status
metiscode agents list idle
metiscode agents list busy
metiscode agents list error

# Remove agents
metiscode agents remove mydev

# Health monitoring
metiscode agents health
metiscode agents cleanup

MCP (Model Context Protocol) Integration

Connect to MCP Servers

# 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 myserver

# Test server capabilities
metiscode mcp test myserver

# Use MCP tools in interactive session
metiscode
> "Use the weather tool from myserver to get current conditions"

MCP Server Management

# List configured servers
metiscode mcp show

# Add 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 myserver

# Disconnect 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.

Authentication Methods

1. Browser Authentication (Recommended)

metiscode
# Select "Authenticate in browser"
# Browser opens -> Log in -> Select agents -> Done

2. API Key Entry

metiscode
# Select "Enter MetisOS API key"
# Paste your mtms_... key from metisos.co/console

Configuration Location

Authentication is stored in:

~/.metis/metis-auth.json

Create Custom Agents

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

Permission Modes

Press Tab 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

Planning Mode

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

Session Approvals

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

Code Previews

Get Claude Code-style before/after diffs:

Approval Required

Operation: 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

Multi-file Operations

# 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"

Session Management

# List recent sessions with enhanced info
/sessions

# Resume a specific session
/resume session-12345

# Continue the last session
/continue

# View active session approvals
/approvals

Memory & Context Commands

/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

Agent.md Files

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

Memory Management

# 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:30

2. 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

File Operations

• 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

Multi-file Operations

• 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

Git Operations (Enhanced)

• 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

GitHub Integration

• github_pr: Pull request management
• github_issue: Issue tracking
• github_repo: Repository operations
• github_workflow: CI/CD workflow management

MCP Operations

• 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

Search & Navigation

• grep: Advanced search with ripgrep
• find_files: Locate files by name/pattern

System Operations

• bash: Execute shell commands (with approval)
• ps: Process listing
• env: Environment variables

Todo Management

• create_todo: Add tasks to session todo list
• update_todo: Modify existing todos
• list_todos: View active todos
• delete_todo: Remove completed todos

Persona System

Metis Code features a sophisticated persona system that allows you to customize AI behavior and personality traits for different development contexts.

Built-in Personas

Default (default)

• Balanced general-purpose coding assistant
• Temperature: 0.2

Friendly 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.3

Senior Developer (senior-dev)

• Expert code reviews and architecture guidance
• Focus on best practices and maintainable code
• Temperature: 0.1

Security Expert (security-expert)

• Specialized security analysis and secure coding
• Vulnerability assessment and threat modeling
• Temperature: 0.1

AI-Powered Persona Generation

Generate custom personas tailored to your specific needs using AI assistance:

# 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"

Interactive Session Persona Management

# 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

Project-Specific Personas

Create project-specific personas that override global settings:

.metis/persona.yaml (Project-specific persona)

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"

Persona Loading Priority

1. Project-specific (.metis/persona.yaml) - highest priority
2. Environment variable (METIS_PERSONA=persona-name)
3. Default persona - fallback

Managing Personas

# CLI Commands
metiscode persona list                           # List all personas
metiscode persona show <name>                    # Show persona details
metiscode persona generate <name> [description]  # Generate new persona
metiscode persona validate <name>                # Validate persona format

# Use specific persona in session
METIS_PERSONA=security-expert metiscode

# Interactive session commands
/persona list                                    # List personas
/persona show senior-dev                        # Show details
/persona generate my-expert "Custom description" # Generate persona

Generated Persona Features

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

Persona Examples

Generate a Testing Expert:

metiscode persona generate qa-expert "Quality assurance specialist focused on testing strategies"

Generate a Frontend Specialist:

metiscode persona generate react-ninja "React expert with modern hooks and TypeScript expertise"

Generate a Database Expert:

metiscode persona generate db-architect "Database design and optimization specialist"

Session Persistence

Automatic Features

• 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

Manual Session Control

# Resume last interrupted session
metiscode --resume

# Start with specific session ID
metiscode --session my-session-id

# View session statistics
/sessions  # Shows duration, file count, message count

Legacy CLI Commands

For backwards compatibility and automation:

# 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 changes

# System info
metiscode status        # System health check

# Tool testing
metiscode exec "ls -la" # Execute shell commands

# Agent management
metiscode agents list   # List sub-agents
metiscode agents stats  # Agent performance

# MCP management
metiscode mcp show      # List MCP servers

Configuration Files

MetisOS Authentication

~/.metis/metis-auth.json (Created automatically after authentication)

{
  "apiKey": "mtms_...",
  "defaultAgentId": "agent_...",
  "agents": [
    {
      "id": "agent_...",
      "name": "My Agent",
      "role": "Senior Developer",
      "model": "llama-3.3-70b-versatile",
      "provider": "groq"
    }
  ],
  "user": {
    "email": "[email protected]",
    "name": "User Name"
  },
  "authenticatedAt": "2026-01-10T..."
}

Project Configuration (Optional)

metis.config.json

{
  "safety": {
    "dryRun": false,
    "requireExecApproval": true
  },
  "ignore": [
    "node_modules/**",
    ".git/**",
    "dist/**"
  ]
}

.metis/mcp-servers.json (MCP Server Configurations)

{
  "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"]
    }
  }
}

Agent.md (Project Instructions)

# 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 features

## Architecture
- Frontend: React + TypeScript + Vite
- Backend: Node.js + Express + TypeScript
- Database: PostgreSQL with Prisma ORM

## Sub-Agents Usage
- Use developer agents for implementation
- Use reviewer agents for code quality
- Use devops agents for deployment

Usage Examples

Multi-Agent Workflow

# Start interactive session
metiscode

# Create specialized team
metiscode agents create developer backend-dev
metiscode agents create reviewer security-reviewer
metiscode agents create devops deploy-engineer

# Coordinate 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"

MCP Integration

# 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"

Using Across Projects

# 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"

Bug Fixing with Debugging Specialist

metiscode agents create debugging-specialist debugger
metiscode agents exec debugger "The application crashes when processing large files. Investigate and fix the memory issue."

Code Review with Security Expert

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."

DevOps Automation

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

Prerequisites

• Node.js 18+
• npm or yarn

Local Development

# Clone repository
git clone https://github.com/your-repo/metis-code
cd metis-code

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start locally
npm start

# Test CLI locally
node dist/cli/index.js --help

Project Structure

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 system

assets/
└── personas/           # Built-in AI personas

tests/                  # Test suite
docs/                   # Documentation

Troubleshooting

Common Issues

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'

Getting Help

# General help
metiscode --help

# Session help
metiscode
> /help

# Check system status
metiscode status

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Run the test suite: npm test
5. Build the project: npm run build
6. Submit a pull request

Development Guidelines

• Follow TypeScript strict mode
• Add tests for new features
• Update documentation for API changes
• Use conventional commit messages
• Ensure all CI checks pass

License

MIT License - see LICENSE file for details.

Links

• 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.