osagent 0.1.15 → 0.1.17

package/README.md

@@ -1,16 +1,21 @@
-# OSAgent
+# OS Agent
 
-An AI-powered coding assistant CLI that runs locally with Ollama or connects to cloud AI providers.
+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
 
-- **Local-first AI**: Works with Ollama for completely offline usage
+- **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 syntax highlighting
-- **Code generation**: Generate, edit, and refactor code with natural language
+- **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/`
 
 ## Installation
 
@@ -23,8 +28,8 @@ npm install -g osagent
 ### From source
 
 ```bash
-git clone https://github.com/osagent/osagent-cli.git
-cd osagent-cli
+git clone https://github.com/robertohluna/osagent.git
+cd osagent
 npm install
 npm run build
 npm link
@@ -32,14 +37,14 @@ npm link
 
 ## Quick Start
 
-### Option 1: Use with Ollama (Local)
+### Option 1: Use with Ollama (Local - Recommended)
 
 1. Install [Ollama](https://ollama.com)
 2. Pull a coding model:
    ```bash
    ollama pull qwen2.5-coder:32b
    ```
-3. Run OSAgent:
+3. Run OS Agent:
    ```bash
    osagent
    ```
@@ -51,7 +56,7 @@ npm link
    ```bash
    export OLLAMA_API_KEY=your-api-key
    ```
-3. Run OSAgent:
+3. Run OS Agent:
    ```bash
    osagent
    ```
@@ -75,36 +80,109 @@ osagent "Create a hello world Python script"
 
 # Use a specific model
 osagent --model qwen2.5-coder:32b
+
+# Resume last session
+osagent --continue
 ```
 
 ### 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
-- `/model` - Switch AI model
-- `/clear` - Clear conversation history
-- `/docs` - Open documentation
-- `/quit` - Exit OSAgent
+- `/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
+
+#### Utilities
+- `/copy` - Copy last response to clipboard
+- `/memory` - View and edit project memory
+- `/tools` - List available tools
+- `/mcp` - Manage MCP servers
+
+### Consultation Mode
+
+OS Agent can ask you clarifying questions as it works to better understand your requirements:
+
+```bash
+/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 below the loading indicator during agent operations.
 
 ### Configuration
 
-OSAgent stores its configuration in `~/.osagent/settings.json`. You can customize:
+OS Agent stores its configuration in `~/.osagent/`:
+
+```
+~/.osagent/
+├── settings.json       # User settings
+├── agents/            # Custom agent definitions (.md, .yaml, .json)
+├── commands/          # Custom slash commands (.toml)
+├── prompts/           # Custom prompts
+└── system.md          # Custom system prompt
+```
 
-- Default model
-- API endpoints
-- Theme settings
-- Tool permissions
+### Custom Agents
+
+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
+```
 
 ### Project Memory
 
-Create an `OSAGENT.md` file in your project root to give OSAgent context about your project:
+Create an `OSAGENT.md` file in your project root to give OS Agent context:
 
 ```bash
 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
@@ -127,16 +205,31 @@ npm run test
 
 # Type check
 npm run typecheck
+
+# Lint
+npm run lint
 ```
 
 ## Architecture
 
-OSAgent is a monorepo with the following packages:
+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
 
-- `osagent` - Root package and CLI entry point
-- `osagent-cli` - Terminal UI and user interaction
-- `osagent-core` - AI engine, tools, and services
-- `osagent-test-utils` - Shared test utilities
+- `Ctrl+C` (twice) - Exit
+- `Ctrl+D` (twice) - Exit
+- `Escape` - Cancel current operation
+- `Tab` - Autocomplete commands
+- `Up/Down` - Navigate history
+- `o` (during loading) - Toggle thinking display
 
 ## License
 
@@ -148,6 +241,6 @@ Contributions are welcome! Please read our contributing guidelines before submit
 
 ## Links
 
-- [Documentation](https://ollama.com/library/qwen2.5-coder)
-- [GitHub](https://github.com/osagent/osagent-cli)
+- [GitHub](https://github.com/robertohluna/osagent)
 - [npm](https://www.npmjs.com/package/osagent)
+- [Issues](https://github.com/robertohluna/osagent/issues)