# OCAI-Agent

**Repository Path**: OpenCloudOS/ocai-agent

## Basic Information

- **Project Name**: OCAI-Agent
- **Description**: 嵌入 OCManager Web 控制台的前端 AI 交互组件，整合通用问答与智能诊断双入口。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OCAI Agent

> An open-source terminal-native AI agent for OpenCloudOS, built in Go.

`ocai-agent` is the open-source distribution of the OCAI Agent project. It ships a TUI
terminal that embeds an LLM-powered agent able to plan tasks, run shell commands inside
a sandbox, manage long-running sessions, and orchestrate sub-agents and skills.

This repository is the upstream for the binaries shipped on:

| Platform     | Binary | Config dir       |
| ------------ | ------ | ---------------- |
| OpenCloudOS  | `ocai` | `~/.ocai_agent/` |

---

## Features

- **TUI terminal** built on Bubble Tea with PTY backing, scrollback, in-app
  selection/copy and a chat-style agent panel.
- **Agent loop** with planning, tool use, sub-agent delegation and structured memory.
- **Sandbox** for shell execution (bubblewrap-friendly), with a pluggable permission
  model.
- **Skills** system: drop-in directories of Markdown + executable scripts the agent can
  discover and call.
- **MCP** (Model Context Protocol) client built in.
- **OpenCloudOS packaging**: Makefile produces the `ocai` binary and matching SRPMs.

## Repository layout

```
README.md
LICENSE / NOTICE / SECURITY.md
CONTRIBUTING.md / CHANGELOG.md / CODE_OF_CONDUCT.md
cmd/            entrypoints (terminal)
internal/       agent, llm, mcp, sandbox, shell, skills, ui, tools, ...
pkg/            reusable libraries (logger, ...)
configs/        OpenCloudOS config templates and shipped skills
```

## Quick start

Requires Go 1.24+.

```bash
# Get the source
cd ocai-agent

# Build the development binary
make build

# Or build a release binary for OpenCloudOS
make build-release        # produces bin/ocai
make build-opencloudos    # alias of build-release

# Run with the agent enabled (creates /etc/ocai_agent/config.json on first run)
make run-agent
```

On first launch, edit `~/.ocai_agent/config.json` and fill in your LLM API key.

## Configuration

OpenCloudOS config templates live under `configs/`:

- `configs/ocai_agent/config.json`     – LLM / agent / UI settings
- `configs/ocai_agent/subagents.json`  – sub-agent definitions
- `configs/ocai_agent/skills/`         – built-in skills

Don't commit real API keys – `.env` and any populated `config.json` are git-ignored.

## Development

```bash
make deps              # go mod download && tidy
make test              # unit tests
make fmt
make lint              # requires golangci-lint
```

## Status

Early open-source release. APIs and on-disk layouts may still change between minor
versions; check [`CHANGELOG.md`](./CHANGELOG.md) before upgrading.

## Contributing

| Document | Description |
|----------|-------------|
| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution workflow |
| [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) | Community guidelines |
| [CHANGELOG.md](./CHANGELOG.md) | Release history |

Contributions are welcome. Please read the documents above before opening issues or
pull requests. For security-sensitive reports please follow [`SECURITY.md`](./SECURITY.md)
instead of filing a public issue.

## License

This project is licensed under **GNU General Public License v2.0** (see
[`LICENSE`](./LICENSE)), consistent with
[oc-manager](../oc-manager/LICENSE). Third-party dependencies are declared in
[`NOTICE`](./NOTICE).

## Security

If you discover a security issue, please report it privately as described in
[`SECURITY.md`](./SECURITY.md). Do not disclose details in public issues.