openAgent

1<p align="center">
2  <h1 align="center">OpenAgent</h1>
3  <p align="center"><strong>The Universal, Local-First AI Agent Platform</strong></p>
4</p>
5 
6<p align="center">
7  <a href="#features">Features</a> •
8  <a href="#quickstart">Quickstart</a> •
9  <a href="#cli-usage">CLI Usage</a> •
10  <a href="#dynamic-tools">Dynamic Tools</a> •
11  <a href="#credential-manager">Credentials</a> •
12  <a href="#local-web-mode">Web Mode</a> •
13  <a href="#architecture">Architecture</a> •
14  <a href="#license">License</a>
15</p>
16 
17---
18 
19## Overview
20 
21**OpenAgent** is a universal, local-first AI agent platform designed to run autonomously on your machine. Beyond software development, OpenAgent is capable of reasoning about arbitrary workflows—integrating with APIs, cloud services, databases, research pipelines, and local environments through a dynamic, persistent tool architecture.
22 
23OpenAgent features a shared core runtime accessible via:
24* **Interactive Terminal TUI** (`openagent`)
25* **Local Web UI** (`openagent web`)
26* **Headless & Scripting CLI** (`openagent run "..."`)
27 
28---
29 
30## Architecture
31 
32```text
33                         OpenAgent
34                            │
35                    ┌───────┴────────┐
36                    │ Agent Runtime  │
37                    └───────┬────────┘
38                            │
39       ┌────────────────────┼────────────────────┐
40       │                    │                    │
41       ▼                    ▼                    ▼
42      TUI                 Web UI                CLI
43       │                    │                    │
44       └────────────────────┼────────────────────┘
45                            │
46                            ▼
47                       Agent Engine
48                            │
49          ┌─────────────────┼─────────────────┐
50          │                 │                 │
51          ▼                 ▼                 ▼
52     Tool Registry    Credential Broker   Permission System
53          │
54     ┌────┴────┐
55     ▼         ▼
56 Built-in   Generated
57  Tools       Tools
58               │
59               ▼
60            Sandbox
61```
62 
63---
64 
65## Key Features
66 
67### 1. Dynamic Tool Creation & Persistent Registry
68When OpenAgent encounters a task requiring an external capability it does not possess, it autonomously creates, validates, sandbox-tests, and registers a persistent tool.
69* **Built-in tools**: `read`, `write`, `edit`, `glob`, `grep`, `bash`, `webfetch`, `websearch`, `question`, `todowrite`, `skill`, `tool_generate`.
70* **Agent-generated tools**: Dynamic tools saved across sessions in `~/.openagent/tools/`.
71* **Tool Management**: Inspect, test, enable, or remove tools via `openagent tools` or `/tools`.
72 
73### 2. Credential Broker & Strict Secret Isolation
74* **Zero Secret Leakage**: The LLM model context never receives the raw credential vault.
75* **Scoped Injection**: Generated tools only receive credentials they explicitly declare and have been authorized for.
76* **Automatic Redaction**: API keys, tokens, and passwords are automatically masked with `[REDACTED]` across logs, session history, TUI/Web output, and error traces.
77* **Management**: View and configure credentials via `openagent credentials` or `/credentials` (without exposing secret values).
78 
79### 3. Multi-Provider AI Support
80Connect to leading AI providers or run offline:
81* Anthropic (Claude 3.7 Sonnet / Opus / Haiku)
82* OpenAI (GPT-4o, o1, o3-mini)
83* Google Gemini (Gemini 2.0 Flash / Pro)
84* Groq, Mistral, xAI, Amazon Bedrock, OpenRouter, Ollama & local models.
85 
86### 4. Fine-Grained Permission System
87Control agent autonomy with clear permission tiers (`allow`, `ask`, `deny`):
88* `filesystem.read` / `filesystem.write`
89* `shell.execute` / `process.spawn`
90* `network.request`
91* `credential.read`
92* `tool.generate`
93 
94---
95 
96## Quickstart
97 
98### Running the Terminal TUI
99```bash
100openagent
101```
102 
103### Running Local Web Mode
104```bash
105openagent web
106```
107Starts the local OpenAgent server at `http://localhost:4096` and opens the browser UI.
108 
109### Running Headless Tasks
110```bash
111openagent run "Summarize recent Git commits and check for any outdated dependencies"
112```
113 
114---
115 
116## CLI Usage
117 
118```bash
119# General help and commands
120openagent --help
121 
122# Dynamic Tool Management
123openagent tools list                    # List built-in and generated tools
124openagent tools inspect <tool_name>     # View tool schema, source, and credentials
125openagent tools remove <tool_name>      # Delete a generated tool
126openagent tools enable <tool_name>      # Enable a tool
127openagent tools disable <tool_name>     # Disable a tool
128 
129# Credential Management
130openagent credentials list              # List configured keys and dependencies
131openagent credentials set <KEY> <VALUE> # Securely store a credential
132openagent credentials remove <KEY>      # Remove a credential
133 
134# Models and Providers
135openagent models                        # List available models
136openagent providers                     # Configure AI providers
137```
138 
139---
140 
141## Development & Testing
142 
143```bash
144# Install dependencies
145bun install
146 
147# Run the OpenAgent dev CLI
148bun dev
149 
150# Run unit and security tests
151bun test
152```
153 
154---
155 
156## Upstream Attribution
157 
158OpenAgent builds upon and extends the open-source foundation originally created by [OpenCode](https://github.com/anomalyco/opencode). We are grateful to the original creators and maintainers.
159 
160## License
161 
162MIT License. See [LICENSE](./LICENSE) for details.
163