https://github.com/johnjallday/ori-agent
A local-first agent manager for running and orchestrating multiple AI agents.
https://github.com/johnjallday/ori-agent
ai-agent ai-assistant aiagent aiagents aiagentsframework go-ai golang
Last synced: 21 days ago
JSON representation
A local-first agent manager for running and orchestrating multiple AI agents.
- Host: GitHub
- URL: https://github.com/johnjallday/ori-agent
- Owner: johnjallday
- License: other
- Created: 2025-08-14T04:59:11.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-02-02T09:59:52.000Z (26 days ago)
- Last Synced: 2026-02-02T10:43:56.597Z (26 days ago)
- Topics: ai-agent, ai-assistant, aiagent, aiagents, aiagentsframework, go-ai, golang
- Language: Go
- Homepage:
- Size: 718 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 
Ori Agent
**Ori Agent** is a local first AI agent management platform. Spin up multiple named agents, each with its own model, prompt, and tool loadout, and run them through a browser UI or API. Agents call plugins (gRPC tools) to act—everything stays on your machine unless you opt into cloud LLMs.
If you want to keep your information local, this is a way to go.
I don't plan on promoting this until Q426 or Q127 (This date may change).
If you are here early, then welcome! Hope you enjoy this.
Let me know, how this is.
## Open-Core Boundary
Ori Agent core is open-source and can be used commercially. Web3/token and marketplace payment services are not included in this repo and are operated privately.
Open-source core includes:
- Agent runtime, orchestration, plugin SDK, and local plugin execution
- UI, settings, and local plugin marketplace management
- Web3 wallet UI for local metadata only (no on-chain operations)
Private services (not included):
- Ori Token issuance, daily credits, cashout, and anti-cheat
- Marketplace payments and Ori-specific monetization flows
Details: `docs/architecture/open-core-boundaries.md`
Additional terms:
- `ORI_SERVICES.md` (private services access)
- `TRADEMARKS.md` (branding and trademark use)
## 🤖 Supported Providers
Ori Agent supports multiple AI providers, giving you flexibility in choosing your preferred AI model:
### Cloud Providers
- **OpenAI**
- Requires: `OPENAI_API_KEY`
- Best for: Production use, latest models, reliable performance
- **Anthropic Claude**
- Requires: `ANTHROPIC_API_KEY`
- Best for: Long context windows, detailed reasoning
### Local Providers
- **Ollama** - Run models locally on your machine
- Requires: Ollama installed and running (http://localhost:11434)
- Best for: Privacy, offline use, cost savings
- Supports: Llama 3, Mistral, Phi-3, and other Ollama models
## 🚀 Quick Start
### For Mac Users
Download and install the DMG from the latest release:
- https://github.com/johnjallday/ori-agent/releases/latest
Open the DMG and drag `OriAgent.app` to Applications.
### For Devs
### Prerequisites
- Go 1.25 or later
- An API key from one of the supported providers (OpenAI, Claude) **OR** Ollama installed locally
### Installation
#### Option 1: macOS DMG Installer (Recommended for macOS)
1. **Download the DMG** from the [latest release](https://github.com/johnjallday/ori-agent/releases/latest)
2. **Open the DMG** and drag `OriAgent.app` to Applications
3. **Handle macOS Security Warning**
When first opening OriAgent, macOS may show one of these warnings:
- *"OriAgent is damaged and can't be opened"* (most common)
- *"Apple cannot verify OriAgent is free of malware"*
**This is normal for open-source apps not notarized by Apple.** To install safely:
**Method 1 - Right-Click (Easiest):**
1. Drag `OriAgent.app` to Applications folder
2. Right-click (or Control+click) `OriAgent.app` in Applications
3. Select "Open" from the menu
4. Click "Open" in the dialog that appears
**Method 2 - Terminal Command:**
```bash
xattr -rc /Applications/OriAgent.app
open /Applications/OriAgent.app
```
After the first launch, you can open normally by double-clicking.
4. **Configure your API key** through the Settings panel in the app, or export it:
```bash
export OPENAI_API_KEY="your-api-key"
```
5. **Access the interface** at `http://localhost:8765`
#### Option 2: Build from Source
1. **Clone the repository**
```bash
git clone https://github.com/johnjallday/ori-agent.git
cd ori-agent
```
2. **Install dependencies**
```bash
go mod tidy
```
3. **Set up your API key** (choose one)
```bash
# For OpenAI
export OPENAI_API_KEY="your-openai-api-key"
# For Claude
export ANTHROPIC_API_KEY="your-anthropic-api-key"
# For Ollama - just make sure it's running
# No API key needed!
```
4. **Build and run**
```bash
./scripts/build.sh
./bin/ori-agent
```
5. **Open your browser**
```
http://localhost:8765
```
#### Option 3: Linux Package Installer
1. **Download the package** from the [latest release](https://github.com/johnjallday/ori-agent/releases/latest):
**Debian/Ubuntu:**
```bash
# Download .deb file
wget https://github.com/johnjallday/ori-agent/releases/latest/download/ori-agent_{version}_amd64.deb
# Install
sudo dpkg -i ori-agent_{version}_amd64.deb
```
**Red Hat/Fedora/CentOS:**
```bash
# Download .rpm file
wget https://github.com/johnjallday/ori-agent/releases/latest/download/ori-agent_{version}_amd64.rpm
# Install
sudo rpm -i ori-agent_{version}_amd64.rpm
```
2. **Configure API key** via environment variable or `/etc/ori-agent/settings.json`
3. **Start the service**:
```bash
sudo systemctl start ori-agent
sudo systemctl enable ori-agent # Auto-start on boot
```
4. **Access the interface** at `http://localhost:8765`
#### Option 4: Windows Archive
1. **Download** `ori-agent_{version}_windows_x86_64.tar.gz` from the [latest release](https://github.com/johnjallday/ori-agent/releases/latest)
2. **Extract** the archive to a folder (e.g., `C:\Program Files\OriAgent`)
3. **Set API key** via Environment Variables or create `settings.json` in the same folder
4. **Run** `ori-agent.exe`
5. **Access the interface** at `http://localhost:8765`
## 🧩 Skills
Ori Agent supports per-agent Skills compatible with the Claude/OpenAI skill format.
### Skill Locations
- `agents//skills` (agent-scoped)
- `agents/skills` (repo-scoped)
- `.agents/skills` (compatibility; lowest priority)
Each Skill is a directory containing `SKILL.md` with YAML frontmatter (`name`, `description`) and a prompt body. Optional `agents/openai.yaml` provides UI metadata and dependency hints.
### Naming Rules
- `name`: lowercase letters, numbers, hyphens only; max 64 chars; must not include `anthropic` or `claude`; no XML tags.
- `description`: required; max 1024 chars; no XML tags.
## 💬 Session Management
Ori Agent includes a comprehensive session management system for organizing and managing your chat conversations.
### Features
- **Persistent Chat Sessions**: All conversations are automatically saved and can be resumed anytime
- **Folder Organization**: Group related sessions into folders for better organization
- **Multi-Tab Support**: Work with multiple sessions simultaneously in separate browser tabs
- **Full-Text Search**: Quickly find messages across all your sessions
- **Tagging System**: Add tags to sessions for easy categorization and filtering
- **Automatic Cleanup**: Optionally clean up old, inactive sessions to manage storage
### Session Storage
Sessions are stored in a SQLite database with an in-memory LRU cache for fast access:
- **Cache**: Recently accessed sessions are kept in memory for instant retrieval
- **Database**: All sessions are persisted to SQLite with full-text search support
- **Hybrid Architecture**: Automatic cache warming and write-through for optimal performance
### Storage Management
Configure session storage limits via the Settings page or `settings.json`:
| Setting | Default | Description |
|---------|---------|-------------|
| `session_cleanup_enabled` | `true` | Enable automatic cleanup of old sessions |
| `session_cleanup_days` | `30` | Days of inactivity before a session is eligible for cleanup |
| `session_max_count` | `1000` | Maximum number of sessions to keep (0 = unlimited) |
**Via Settings Page:**
1. Navigate to Settings → Session Management
2. Configure cleanup options and limits
3. View current storage statistics
4. Run manual cleanup if needed
**Via settings.json:**
```json
{
"session_cleanup_enabled": true,
"session_cleanup_days": 30,
"session_max_count": 1000
}
```
### Session API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/sessions` | GET | List all sessions (with pagination, filtering) |
| `/api/sessions` | POST | Create a new session |
| `/api/sessions/{id}` | GET | Get a specific session |
| `/api/sessions/{id}` | PUT | Update session metadata |
| `/api/sessions/{id}` | DELETE | Delete a session |
| `/api/sessions/{id}/messages` | GET | Get messages for a session |
| `/api/sessions/{id}/messages` | POST | Add a message to a session |
| `/api/sessions/search` | GET | Search across all sessions |
| `/api/sessions/storage/stats` | GET | Get storage statistics |
| `/api/sessions/cleanup` | POST | Trigger manual cleanup |
### Performance
The session system is optimized for handling many sessions efficiently:
- **100+ Sessions**: Tested to handle 150+ sessions with sub-millisecond list operations
- **Concurrent Access**: Thread-safe operations support multiple tabs and clients
- **Efficient Search**: Full-text search returns results in under 500µs for typical workloads
## 🔌 Plugin Development
Ori Agent uses a plugin system that lets you extend functionality with custom tools. Build plugins as standalone executables that communicate via gRPC.
### Plugin Optimization APIs (New!)
We've introduced three powerful APIs that dramatically simplify plugin development:
#### 1. **YAML-Based Tool Definitions** (70% less code!)
Define parameters in `plugin.yaml` instead of code:
```yaml
tool_definition:
description: "Your tool description"
parameters:
- name: operation
type: string
required: true
enum: [create, list, delete]
- name: count
type: integer
min: 1
max: 100
```
```go
func (t *MyTool) Definition() pluginapi.Tool {
tool, _ := t.GetToolDefinition() // Auto-loads from plugin.yaml
return tool
}
```
Checkout Example Plugins
| Plugin | Description | Type |
|--------|-------------|------|
| math | Perform basic math operations: add, subtract, multiply, divide | Example |
| minimal | Minimal example tool demonstrating YAML-based configuration. Supports echo and status operations. | Example |
| result-handler | Handle actions on chat results like opening directories, files, or URLs | Example |
| weather | Get weather for a given location | Example |
| webapp | Example tool with web interface. Manages a simple list of items. | Example |
#### 2. **Template Rendering API**
Serve beautiful web pages with Go templates:
```yaml
# plugin.yaml
assets:
- templates
```
```go
html, err := pluginapi.RenderTemplate(assetsFS, "templates/page.html", data)
```
### Getting Started with Plugins
- **Documentation**: See [PLUGIN_OPTIMIZATION_GUIDE.md](PLUGIN_OPTIMIZATION_GUIDE.md) for complete migration guide
- **Examples**: Check out `example_plugins/minimal/` and `example_plugins/webapp/`
- **Reference**: See [CLAUDE.md](CLAUDE.md) for detailed plugin development patterns
### Building a Plugin
```bash
cd example_plugins/minimal
go build -o minimal-plugin main.go
cp minimal-plugin ../../uploaded_plugins/
```
Restart Ori Agent, and your plugin will be automatically loaded!
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 💬 Support
- 🐛 **Issues**: [GitHub Issues](https://github.com/johnjallday/ori-agent/issues)
- 💡 **Feature Requests**: Open an issue with the "enhancement" label
- 💬 **Discussions**: [GitHub Discussions](https://github.com/johnjallday/ori-agent/discussions)
While this app is very functional, there will be a lot of breaking changes. Feel free to give feedbacks.
MVP = v0.1.0 => I will be releasing at least once a week until v0.0.99
## 🛣️Roadmap
v0.0.60 Python Support
v0.0.70
buymeacoffee.com/johnjallday
---
Made with ❤️ using Go and modern web technologies