OS Agent

An AI-powered autonomous coding assistant CLI that runs locally with Ollama or connects to cloud AI providers. Built for developers who want full control over their AI coding assistant.

Features

• Smart Onboarding: Auto-detects your system, tools, and project on first run
• Local-first AI: Works with Ollama for completely private, offline usage
• Cloud support: Connect to Ollama Cloud or OpenAI-compatible APIs
• Interactive CLI: Beautiful terminal interface with monochrome green theme
• Autonomous coding: Generate, edit, and refactor code with natural language
• Multi-file editing: Make changes across your entire project
• Git integration: Automatic commits and PR creation
• Consultation mode: AI asks clarifying questions to better understand your needs
• Conversation persistence: Resume previous sessions with /continue
• System health checks: Built-in diagnostics with /doctor
• Extensible: MCP (Model Context Protocol) support for custom tools
• Custom agents: Define your own specialized agents in ~/.osagent/agents/
• Custom commands: Create custom slash commands in ~/.osagent/commands/
• Custom skills: Create skill plugins for multi-step workflows
• Multi-agent orchestration: Automatic skill detection and agent dispatch
• Episodic memory: Session tracking and learning from past interactions
• Vector memory: Semantic search over session history with ChromaDB
• Embeddings: Ollama embeddings with OpenRouter fallback
• Advanced hooks: 12 subagent hooks for lifecycle, memory, and skill events

Installation

From npm (recommended)

npm install -g osagent

From source

git clone https://github.com/robertohluna/osagent.git
cd osagent
npm install
npm run build
npm link

Quick Start

Option 1: Use with Ollama (Local - Recommended)

1. Install Ollama
2. Pull a coding model:

   ollama pull qwen2.5-coder:32b

3. Run OS Agent:

   osagent

Option 2: Use with Ollama Cloud

1. Get an API key from Ollama Cloud
2. Set your API key:

   export OLLAMA_API_KEY=your-api-key

3. Run OS Agent:

   osagent

Option 3: Use with OpenAI-compatible APIs

osagent --auth openai

Usage

Basic Commands

# Start interactive mode
osagent

# Start with a prompt
osagent "Explain this codebase"

# Use a specific model
osagent --model qwen2.5-coder:32b

# Resume last conversation
osagent --continue

# Print a file and ask about it
osagent "What does this do?" < src/main.ts

# Run health check
osagent doctor

# Dangerous mode (auto-accept all tool executions)
osagent --dangerously

Slash Commands

Once in the interactive mode, you can use these commands:

General

• /help - Show available commands
• /about - Show version and system info
• /settings - View and edit settings
• /quit or /q - Exit OS Agent

Model & AI

• /model - Switch AI model (supports local Ollama models)
• /agents - Manage custom agents
• /consult - Toggle consultation mode (AI asks clarifying questions)

Conversation

• /continue - Resume the most recent conversation
• /continue list - List recent sessions to resume
• /reset - Clear conversation and start fresh
• /clear - Clear the screen
• /chat save <tag> - Save conversation checkpoint
• /chat resume <tag> - Resume from checkpoint

Safety & Permissions

• /dangerously or /yolo - Toggle auto-accept mode for tool executions
• /permissions - View and manage tool permissions

System

• /doctor - Check system health and updates
• /doctor update - Auto-update to latest version
• /doctor init - Initialize ~/.osagent/ directory structure
• /view - View system architecture and configuration
• /view config - Current configuration
• /view files - Configuration files
• /view models - Supported models
• /context or /ctx - View context window usage and token stats

Utilities

• /copy - Copy last response to clipboard
• /memory - View and edit project memory
• /tools - List available tools
• /mcp - Manage MCP servers

Status Bar

While OS Agent works, you'll see a real-time status bar showing:

• Current activity with spinner
• Token usage (input ↑ / output ↓)
• Elapsed time
• Task progress and list

┌─────────────────────────────────────────────────────────┐
│ ◐ Writing tests for auth module... (2/5)    ↑12.3k ↓8.2k 2m 15s │
│ ├─ ○ Create test file                                   │
│ ├─ ◐ Writing unit tests                                │
│ └─ ○ Run tests and fix errors                          │
└─────────────────────────────────────────────────────────┘

Consultation Mode

OS Agent can ask you clarifying questions as it works to better understand your requirements:

/consult on        # Active mode - questions shown while agent works
/consult blocking  # Blocking mode - high-priority questions pause the agent
/consult off       # Disable consultation
/consult context   # View collected context

Questions appear in a dedicated panel below the status bar during agent operations.

Vector Memory (Optional)

For semantic search over session history, start ChromaDB:

# Start ChromaDB with Docker
docker compose -f docker/docker-compose.yml up -d

# Ensure Ollama has the embedding model
ollama pull nomic-embed-text

Multi-Agent Orchestration

OS Agent features an intelligent orchestration system that automatically:

• Detects skills in your prompts (debugging, testing, refactoring, etc.)
• Selects the best agent for each task based on capabilities
• Dispatches execution to specialized subagents
• Tracks progress with real-time status updates

The orchestrator runs transparently - just describe what you want and OS Agent handles the rest.

Episodic Memory

OS Agent learns from your sessions:

• Records episodes of your interactions automatically
• Tracks actions including tools used and files modified
• Saves outcomes for future reference
• Enables recall of past patterns and solutions

Episodes are stored locally in ~/.osagent/episodes/.

Configuration

OS Agent stores its configuration in ~/.osagent/:

~/.osagent/
├── settings.json       # User settings
├── agents/            # Custom agent definitions (.md, .yaml, .json)
├── commands/          # Custom slash commands (.toml)
├── skills/            # Custom skill plugins (.yaml)
├── prompts/           # Custom prompts
├── episodes/          # Episodic memory storage
└── system.md          # Custom system prompt

Custom Agents

Create custom agents in ~/.osagent/agents/:

# ~/.osagent/agents/my-agent.yaml
name: my-agent
description: A specialized agent for my use case
systemPrompt: You are an expert in...
model: qwen2.5-coder:32b

Project Memory

Create an OSAGENT.md file in your project root to give OS Agent context:

osagent /init

Supported Models

Cloud Models (Ollama Cloud)

• qwen3-coder:480b-cloud - Most powerful (256K context)
• qwen3-coder:30b - Efficient (30B params, 3.3B active)

Local Models (Ollama)

• qwen2.5-coder:32b - Best local coding model (~20GB VRAM)
• qwen2.5-coder:14b - Great balance (~10GB VRAM)
• qwen2.5-coder:7b - Good for limited VRAM (~5GB)
• codellama:34b - Meta's coding model
• deepseek-coder-v2:16b - Efficient MoE model
• llama3.2:latest - General purpose

Requirements

• Node.js >= 20.0.0
• Ollama (for local usage) or API key for cloud providers

Development

# Install dependencies
npm install

# Build all packages
npm run build

# Run in development mode
npm run start

# Run tests
npm run test

# Type check
npm run typecheck

# Lint
npm run lint

Architecture

OS Agent is a monorepo with the following packages:

packages/
├── cli/          # Terminal UI and user interaction (React/Ink)
├── core/         # AI engine, tools, and services
├── test-utils/   # Shared test utilities
└── vscode-ide-companion/  # VS Code extension

Keyboard Shortcuts

General

• Ctrl+C - Cancel current operation / Exit (press twice)
• Ctrl+D - Exit
• Escape - Cancel operation / Clear input
• Tab - Autocomplete commands
• Up/Down - Navigate history
• ? - Show shortcuts help

During Operations

• Ctrl+O - Expand/collapse output
• Ctrl+Y - Toggle todo list visibility
• Ctrl+E - Toggle agent detail level
• Ctrl+F - Focus embedded shell

Text Editing

• Ctrl+L - Clear screen
• Ctrl+A - Move to start of line
• Ctrl+E - Move to end of line
• Ctrl+K - Delete to end of line
• Ctrl+U - Delete to start of line
• Shift+Enter - Insert newline

Recent Updates

v0.1.79 - IDE Terminal Compatibility

• Migrated all dialogs from custom useKeypress to Ink's useInput hook
• Fixes arrow key issues in VS Code, Cursor, and other IDE terminals
• Arrow keys no longer print escape sequences (^[[A^[[B) in dialogs
• Improved compatibility with IDE terminals that don't support raw mode

v0.1.66 - Focus Management

• New useFocusedKeypress hook for enforced focus management
• Prevents keypress conflicts between dialogs and main UI
• Required isFocused parameter catches bugs at compile time

v0.1.65 - Input Routing Fix

• Fixed keyboard input routing issues with selectors
• Arrow keys and Enter now properly isolated to focused component
• No more keypress "leakage" between dialogs

v0.1.64 - UI Improvements

• Tree-view style tool display with ├─ └─ connectors
• Expandable results with Ctrl+O
• Token counts and duration stats
• Sleeker ASCII art header
• Minimal init banner

v0.1.63 - Stability Fix

• Fixed infinite loop on startup (Maximum update depth exceeded)
• Improved React effect dependency management

v0.1.59 - Terminal Stability

• Fixed EIO error crash on stdin
• Graceful handling of TTY disconnects
• Stable arrow key navigation in selectors

See KNOWN_ISSUES.md for detailed issue tracking.

License

Apache-2.0

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Links

• GitHub
• npm
• Issues