OS Agent - AI-powered CLI for autonomous coding with Ollama Cloud and Qwen models
npm install osagentAn 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.
- 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
``bash`
npm install -g osagent
`bash`
git clone https://github.com/robertohluna/osagent.git
cd osagent
npm install
npm run build
npm link
Never use sudo with npm! Using sudo npm install -g creates permission problems.
If you see permission errors:
`bashFix npm cache permissions
sudo chown -R $(whoami) ~/.npm
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 | bashRestart terminal, then:
nvm install 20
nvm use 20Now 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
osagentStart with a prompt
osagent "Explain this codebase"Use a specific model
osagent --model qwen2.5-coder:32bResume last conversation
osagent --continuePrint a file and ask about it
osagent "What does this do?" < src/main.tsRun health check
osagent doctorDangerous 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 -dEnsure 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 purposeRequirements
- Node.js >= 20.0.0
- Ollama (for local usage) or API key for cloud providers
Development
`bash
Install dependencies
npm installBuild all packages
npm run buildRun in development mode
npm run startRun tests
npm run testType check
npm run typecheckLint
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- 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
Apache-2.0
Contributions are welcome! Please read our contributing guidelines before submitting PRs.