osagent

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

$3

``bash
npm install -g osagent
`

$3

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

$3

Never use sudo with npm! Using sudo npm install -g creates permission problems.

If you see permission errors:

`bash


Fix npm cache permissions

sudo chown -R $(whoami) ~/.npm

If using nvm, also fix nvm directory

sudo chown -R $(whoami) ~/.nvm

Clear npm cache

npm cache clean --force

Now install without sudo

npm install -g osagent
`

If updates don't take effect (old version showing):

`bash
npm cache clean --force
npm install -g osagent@latest --force
osagent --version
`

Recommended: Use nvm to avoid permission issues entirely:

`bash


Install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

Restart terminal, then:

nvm install 20
nvm use 20

Now npm never needs sudo

npm install -g osagent
`

Quick Start

$3

1. Install Ollama
2. Pull a coding model:
`bash
ollama pull qwen2.5-coder:32b
`
3. Run osagent:
`bash
osagent
`

$3

1. Get an API key from Ollama Cloud
2. Set your API key:
`bash
export OLLAMA_API_KEY=your-api-key
`
3. Run osagent:
`bash
osagent
`

$3

1. Get an API key from Anthropic Console
2. Set your API key:
`bash
export ANTHROPIC_API_KEY=your-api-key
`
3. Run osagent:
`bash
osagent --auth anthropic
`

$3

1. Get an API key from GROQ Console
2. Set your API key:
`bash
export GROQ_API_KEY=your-api-key
`
3. Run osagent:
`bash
osagent --auth groq
`

$3

`bash
osagent --auth openai
`

Usage

$3

`bash


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
`

$3

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 osagent

#### Model & AI

- /model - Switch AI model (opens model selector)
- /model list - List available models for current provider
- /model info - Show current model details
- /model - Switch to a specific model
- /provider - Switch AI provider (Ollama, Anthropic, GROQ, OpenAI)
- /agents - Manage custom agents
- /consult - Manage 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 - Save conversation checkpoint
- /chat resume - 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

$3

While osagent 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 │
└─────────────────────────────────────────────────────────┘
`

$3

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

`bash
/consult active # Active mode - questions shown while agent works
/consult blocking # Blocking mode - high-priority questions pause the agent
/consult status # Show current consultation mode and stats
/consult context # View collected context
/consult clear # Clear collected consultation context
/consult demo # Run a demonstration of consultation features
`

Consultation is always enabled. Use /consult active or /consult blocking to switch between modes. Questions appear in a dedicated panel below the status bar during agent operations.

$3

For semantic search over session history, start ChromaDB:

`bash


Start ChromaDB with Docker

docker compose -f docker/docker-compose.yml up -d

Ensure Ollama has the embedding model

ollama pull nomic-embed-text
`

$3

osagent 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 osagent handles the rest.

$3

osagent 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/.

$3

osagent stores its configuration in ~/.osagent/ (created automatically on first run):

`
~/.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
`

$3

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

`yaml


~/.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
`

$3

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

`bash
osagent /init
`

Supported Models

$3

- qwen3-coder:480b-cloud - Most powerful (256K context)
- kimi-k2.5:cloud - High-performance coding model (131K context)
- qwen3-coder:30b - Efficient (30B params, 3.3B active)

$3

- moonshotai/kimi-k2-instruct-0905 - Best coding model (256K context, ~200 tok/s)
- moonshotai/kimi-k2-instruct - Kimi K2 (256K context)
- llama-3.3-70b-versatile - Versatile general coding
- llama-3.1-8b-instant - Ultra-fast for simple tasks

$3

- claude-opus-4-5-20251101 - Most powerful
- claude-sonnet-4-5-20250929 - Best balance (recommended)
- claude-haiku-4-5-20251001 - Fastest

$3

- 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

`bash


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

osagent 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

$3

- 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

$3

- Ctrl+O - Expand/collapse output
- Ctrl+Y - Toggle todo list visibility

$3

- 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

Documentation

- ARCHITECTURE.md - System architecture, message flow, content generators, and tool system
- CHANGELOG.md - Full version history and release notes
- docs/ - Detailed documentation on CLI, tools, core APIs, and features
- docs/reference/ - System architecture deep-dive, UI/UX flow, tech stack

License

Apache-2.0

Contributing

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

Links

- GitHub
- npm
- Issues