Octomind – smart AI assistant in CLI

by donhardman 6 months ago

xterm-256color • zsh 263 views

Octomind 🤖 - AI-Powered Development Assistant

Transform your development workflow with AI conversations that understand your codebase

Octomind is an AI-powered development assistant that helps you understand, analyze, and interact with your codebase through natural language conversations. No complex setup, no indexing—just intelligent AI sessions with built-in development tools.

✨ Why Octomind?

🎯 Session-First Architecture - Everything happens in interactive AI conversations
🛠️ Built-in Development Tools - File operations, batch editing, code analysis, shell commands via MCP
🌐 Multi-Provider AI Support - OpenRouter, OpenAI, Anthropic, Google, Amazon, Cloudflare
🖼️ Multimodal Vision Support - Analyze images, screenshots, diagrams with AI across all providers
💰 Cost Tracking & Optimization - Real-time usage monitoring with detailed reporting
🔧 Role-Based Configuration - Developer (full tools) and Assistant (chat-only) modes

🚀 Quick Start

# Install Octomind
curl -fsSL https://raw.githubusercontent.com/muvon/octomind/main/install.sh | bash

# Set your AI provider API key
export OPENROUTER_API_KEY="your_key"

# Start coding with AI
octomind session

💬 How It Works

Instead of complex command-line tools, simply talk to Octomind:

> "How does authentication work in this project?"
[AI analyzes project structure, finds auth-related files, explains implementation]

> "Add error handling to the login function"
[AI examines login code, implements error handling, shows changes]

> "Rename 'processData' to 'processUserData' across all files"
[AI finds all occurrences, performs batch edit across multiple files]

> /image screenshot.png
> "What's wrong with this UI layout?"
[AI analyzes the image, identifies layout issues, suggests CSS fixes]

> "Why is the build failing?"
[AI checks build errors, analyzes code, suggests fixes]

> agent_code_reviewer(task="Review this function for performance issues")
[Routes task to specialized code review AI agent with development tools]

> /report
[Shows: $0.02 spent, 3 requests, 5 tool calls, timing analysis]

🌐 Supported AI Providers

Provider	Format	Features
OpenRouter	`openrouter:provider/model`	Multi-provider access, caching, vision models
OpenAI	`openai:model-name`	Direct API, cost calculation, GPT-4o vision
Anthropic	`anthropic:model-name`	Claude models, caching, Claude 3+ vision
Google	`google:model-name`	Vertex AI, Gemini 1.5+ vision support
Amazon	`amazon:model-name`	Bedrock models, AWS integration, Claude vision
Cloudflare	`cloudflare:model-name`	Edge AI, fast inference, Llama 3.2 vision

🛠️ Installation & Setup

Installation Options

# One-line install (recommended)
curl -fsSL https://raw.githubusercontent.com/muvon/octomind/main/install.sh | bash

# Build from source
cargo install --git https://github.com/muvon/octomind.git

# Manual download from releases
# See: https://github.com/muvon/octomind/releases

Basic Setup

# Set your AI provider API key
export OPENROUTER_API_KEY="your_key"  # or OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

# Create configuration (optional - uses smart defaults)
octomind config

# Start your first session
octomind session

Essential Commands

# Development session (full tools)
octomind session

# Chat-only session
octomind session --role=assistant

# Resume previous session
octomind session --resume my_session

# Use specific model
octomind session --model "openrouter:anthropic/claude-3.5-sonnet"

🎮 Session Commands

Within any session, use these commands:

/help - Show available commands and features
/image <path> - Attach image to your next message (PNG, JPEG, GIF, WebP, BMP)
/model [model] - View or change current AI model
/info - Display token usage and costs
/report - Generate detailed usage report with cost breakdown
/cache - Mark cache checkpoint for cost savings
/layers - Toggle layered processing on/off
/reduce - Compress session history using configured reducer layer
/loglevel [debug|info|none] - Set log level
/exit - Exit current session

🔧 Configuration

Octomind uses a flexible configuration system with smart defaults. Configuration is optional for basic usage.

View Configuration Template: config-templates/default.toml

# Generate default config
octomind config

# Validate configuration
octomind config --validate

# View current settings
octomind config --show

Key Configuration Features:

Environment variable precedence for security
Role-based configurations (developer/assistant)
MCP server registry for tool integration
Cost thresholds and performance tuning

📖 Documentation

📚 Complete Documentation - Comprehensive guides and references

Quick Navigation

Installation Guide - Detailed installation methods and building from source
Overview - Introduction and core concepts
Configuration Guide - Configuration system, templates, and customization
AI Providers - Provider setup, API keys, and model selection
Sessions Guide - Interactive sessions, commands, and workflow
Advanced Features - MCP tools, layered architecture, and extensibility
Command Layers - Specialized AI helpers and command processing

🚀 Contributing

Contributions are welcome! We appreciate your help in making Octomind better.

Development Areas:

AI Providers: Add new providers in src/session/providers/
MCP Tools: Extend tool capabilities via MCP server registry
Documentation: Improve guides and examples

# Development setup
git clone https://github.com/muvon/octomind
cd octomind
cargo build --release
cargo test

Requirements: Rust 1.70+, Cargo, API key from supported providers

🆘 Troubleshooting

Common Issues:

Configuration Errors: Check system config directory or regenerate with octomind config
Missing API Keys: Set environment variables for your AI provider
Invalid Model Format: Use provider:model format (e.g., openrouter:anthropic/claude-3.5-sonnet)
Session Issues: Use /loglevel debug to enable detailed logging

Getting Help:

🐛 Issues: GitHub Issues
📖 Documentation: Complete Documentation
✉️ Email: opensource@muvon.io

📞 Support & Contact

🏢 Company: Muvon Un Limited (Hong Kong)
🌐 Website: muvon.io
📦 Product Page: octomind.muvon.io
📧 Email: opensource@muvon.io
🐛 Issues: GitHub Issues

⚖️ License

More by donhardman

Showcase for assist.nvim plugin 2:13

by donhardman 1 year ago

Octocode Neovim Plugin – semantic search on your codebase 0:26

by donhardman 5 months ago

See all

https://asciinema.org/a/723123

Copied!

Append ?t=30 to start the playback at 30s, ?t=3:20 to start the playback at 3m 20s.

See sharing docs for more link customization options.

Embed as image link

Use snippets below to display a preview image linking to this recording.
Ideal for places where scripts are not allowed, such as project README files.

HTML:

<a href="https://asciinema.org/a/723123" target="_blank"><img src="https://asciinema.org/a/723123.svg" /></a>

Copied!

Markdown:

[![asciicast](https://asciinema.org/a/723123.svg)](https://asciinema.org/a/723123)

Copied!

Embed the player

If you're embedding on your own page or on a site which permits script tags, you can use the full player widget:

<script src="https://asciinema.org/a/723123.js" id="asciicast-723123" async="true"></script>

Copied!

Paste the above script tag where you want the player to be displayed on your page.

See embedding docs for more player customization options.

You can download this recording in asciicast v2 format, as a .cast file.

Download

Replay in terminal

You can replay the downloaded recording in your terminal using the asciinema play command:

asciinema play 723123.cast

Copied!

If you don't have asciinema CLI installed then see installation instructions.

Use with stand-alone player on your website

Download asciinema player from the releases page (you only need .js and .css file), then use it like this:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" type="text/css" href="/assets/asciinema-player.css" />
</head>
<body>
  <div id="player"></div>
  <script src="/assets/asciinema-player.min.js"></script>
  <script>
    AsciinemaPlayer.create(
      '/assets/723123.cast',
      document.getElementById('player'),
      { cols: 87, rows: 28 }
    );
  </script>
</body>
</html>

See asciinema player quick-start guide for full usage instructions.

While this site doesn't provide GIF conversion at the moment, you can still do it yourself with the help of asciinema GIF generator utility - agg.

Once you have it installed, generate a GIF with the following command:

agg https://asciinema.org/a/723123 demo.gif

Copied!

Or, if you already downloaded the recording file:

agg demo.cast demo.gif

Copied!

Check agg --help for all available options. You can change font family and size, select color theme, adjust speed and more.

See agg manual for full usage instructions.