内容
<p align="center">
<a href="https://discord.gg/vxdZuT5WuE"><img src="assets/discord-ribbon.svg" alt="Join the APX community on Discord — discord.gg/vxdZuT5WuE" width="820"></a>
</p>
<p align="center">
<img src="assets/banner.webp" alt="APX — Meet your crew. Your crew of AI agents, running on your machine" width="820">
</p>
<h3 align="center">Meet your crew.</h3>
<p align="center">
<b>APX</b> (<b>A</b>gent <b>P</b>roject e<b>X</b>ecutable) is an <b>open-source Agent OS</b> for running AI agents on your own machine.<br>
Your crew remembers in plain files, hands work to each other, and works from Claude Code, Codex, Telegram, WhatsApp and your phone.<br>
One machine. One context. Your whole crew. Built on the
<a href="https://github.com/agentprojectcontext/agentprojectcontext">APC protocol</a>.
</p>
<p align="center">
<a href="https://agentprojectcontext.github.io/apx/"><img src="https://img.shields.io/badge/Website-agentprojectcontext.github.io-3fb950?style=flat-square&logo=googlechrome&logoColor=white" alt="Website"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-3fb950?style=flat-square" alt="License: MIT"></a>
<img src="https://img.shields.io/badge/Node.js-22%2B-3fb950?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 22+">
<a href="https://github.com/agentprojectcontext/agentprojectcontext"><img src="https://img.shields.io/badge/Protocol-APC-3fb950?style=flat-square" alt="APC protocol"></a>
<a href="https://discord.gg/vxdZuT5WuE"><img src="https://img.shields.io/badge/Discord-join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
</p>
<p align="center">
<b><a href="https://agentprojectcontext.github.io/apx/">🌐 Visit the website</a></b> ·
<a href="#quick-start">Quick start</a> ·
<a href="#examples">Examples</a> ·
<a href="#web-admin">Web admin</a> ·
<a href="#use-cases">Use cases</a> ·
<a href="#android-app">Android app</a> ·
<a href="https://github.com/agentprojectcontext/agentprojectcontext">APC spec</a>
</p>
> APX is the reference implementation of the [APC protocol](https://github.com/agentprojectcontext/agentprojectcontext).
> APX is to APC what a language SDK is to a protocol spec.
## What APX is
APX is a daemon + CLI that brings the APC convention to life:
- **Daemon** — a local HTTP server that manages projects, agents, sessions, and message logs
- **CLI** (`apx`) — commands for running agents, reading memory, tailing messages, managing sessions
- **Web admin** — a local web UI served by the daemon to browse projects, agents, sessions, and MCPs from the browser
- **Runtimes** — bridges to Claude Code, Codex, OpenCode, Aider
- **Engines** — direct LLM calls via Anthropic, OpenAI, Gemini, Ollama, or a mock
- **Plugins** — Telegram bot integration out of the box
- **MCP support** — each agent can expose or consume MCP servers
APX is opinionated about storage: the filesystem is the source of truth. Project definitions and curated memory live in the repo. Runtime state such as sessions, conversations, messages, and caches lives in `~/.apx/` and is never committed.
<p align="center">
<a href="https://agentprojectcontext.github.io/apx/"><img src="assets/demo-group-chat.gif" alt="The APX web panel: a group chat where Lucía plans a Black Friday campaign and mentions Vera and Tomás, who answer in the same thread" width="820"></a><br>
<sub>Your crew in a group chat: mention one agent and it pulls in the others. <a href="https://agentprojectcontext.github.io/apx/">See more of your crew on the website →</a></sub>
</p>
## Quick start
Three steps from nothing to your crew in the browser:
```bash
# 1 · Install (Node.js 22+)
npm install -g @agentprojectcontext/apx
# 2 · Set up — interactive wizard: provider → model → channels → starts the daemon.
# It ends by printing the address of your panel.
apx setup
# 3 · Open the web panel
open http://localhost:7430 # macOS · on Linux: xdg-open · or paste it in any browser
```
That's the panel: chats, agents, tasks, routines and code sessions, all local. Want it on your
phone too? `apx panel share` prints an address for your network (or `apx panel tailscale on`
to reach it from anywhere on your tailnet) — open it and add it to your home screen.
Prefer the terminal? Everything the panel does, the CLI does too:
```bash
# In any directory with an AGENTS.md, register the project
apx init
# Spawn an agent with a full external runtime
apx run sofia --runtime claude-code "Review the open PRs and summarize them"
# Or a quick one-shot LLM exec
apx exec sofia "What is my role in this project?"
# Watch what's happening
apx messages tail
```
## Examples
Real commands — copy one, point it at an agent like `sofia`, and APX routes it to the right
runtime. The session transcript and its summary land in `~/.apx/`; only curated
memory and the agent definition live in `.apc/`.
| What | Command |
|------|---------|
| Register a project | `apx init` |
| Spawn an agent (full runtime) | `apx run sofia --runtime claude-code "Review the open PRs and summarize them"` |
| Ask a quick question (one-shot) | `apx exec sofia "What is my role in this project?"` |
| Read an agent's memory | `apx memory sofia` |
| Switch runtime, same context | `apx run sofia --runtime codex "Add tests for the parser"` |
| Watch what's happening | `apx messages tail` |
## Use cases
- **Review PRs across any runtime** — point an agent at your repo; APX routes to Claude Code and falls back to Codex or OpenCode if one isn't installed. The session and its summary land in `~/.apx/`.
- **Operate your agents from Telegram** — talk to project agents from your phone. Identity roles gate who can do what, and every message is logged per channel for a full audit trail.
- **Memory that lives in your repo** — curated, per-agent memory is plain markdown, committed and reviewable alongside your code. No vendor database, no hidden state, no lock-in.
- **Run the same prompt across engines** — send one prompt through Anthropic, OpenAI, Gemini or a local Ollama model with `apx exec`, configured per project or globally.
## Installation
```bash
npm install -g @agentprojectcontext/apx
```
Requires Node.js 22+. The daemon starts automatically on first `apx` call.
## Android app
APX has a native Android app — the phone surface, plus notifications, the floating mascot
and Android Auto. It is **not on Google Play**: it installs from a file.
```bash
apx android install # phone plugged in: installs, opens the USB tunnel and pairs
```
Or download it straight to the phone — this link always points at the newest signed build:
**[github.com/agentprojectcontext/apx/releases/download/android-latest/apx.apk](https://github.com/agentprojectcontext/apx/releases/download/android-latest/apx.apk)**
Which address the app connects to is the decision that matters: the USB tunnel
(`127.0.0.1`) dies with the cable, your LAN (`apx panel share`) stops at the front door, and
Tailscale (`apx panel tailscale on`) works from anywhere with a real certificate.
[Install on Android](https://agentprojectcontext.github.io/apx/docs/surfaces/install-android/)
walks through all three. iPhone has no APK — the panel installs as a web app instead.
## Web admin
APX ships a local **web admin** — the same runtime, in your browser. The daemon serves a
single-page app so you can browse and manage everything the CLI does without leaving the UI:
- **Projects & agents** — see registered projects, open agents, edit roles, models, and skills
- **Sessions & messages** — read past sessions and tail live activity across every channel
- **MCPs, engines & channels** — review MCP servers, configure engines, and manage Telegram/desktop
It runs entirely on your machine. Start the daemon (any `apx` call does this) and open:
```bash
apx # ensures the daemon is up
open http://localhost:7430 # macOS — or just visit it in any browser
```
The web admin is served from `src/interfaces/web/dist` at the daemon port (`7430` by default,
override with `APX_PORT`). Nothing is sent anywhere — it talks to the local daemon only.
## Project layout
Project context — committed to the repository:
```text
project-root/
├── AGENTS.md ← agent definitions
└── .apc/
├── project.json ← project metadata + stable "id"
├── agents/
│ └── <slug>.md ← agent definition (role, model, skills…)
├── mcps.json ← MCP servers available to this project
├── skills/ ← reusable skill prompts
└── commands/ ← custom slash commands
```
Runtime state — local machine only, never committed:
```text
~/.apx/projects/<project-id>/
├── messages/ ← local message history
└── agents/
├── <slug>/
│ ├── sessions/ ← one .md per runtime invocation
│ └── conversations/ ← LLM conversation threads
└── default/ ← fallback when no agent role is active
└── sessions/
```
## Core commands
```bash
apx init [path] # initialize a project
apx agent list # list agents
apx agent add <slug> --role R --model M # add an agent
apx memory <slug> # read agent memory
apx memory <slug> --append "<note>" # append to memory
apx run <slug> --runtime claude-code "<prompt>" # full runtime session
apx run <slug> --runtime cursor-agent "<prompt>" # Cursor Agent runtime
apx exec <slug> "<prompt>" # quick LLM call
apx session list <slug> # list past sessions
apx messages tail # last 50 messages, all channels
apx messages chat --channel telegram # chat view with user/agent/system type
apx messages tail --channel runtime # only agent invocations
```
## Message channels
Activity belongs to APX runtime state, not `.apc/`. Message storage is local to APX, under
`~/.apx/`:
JSONL messages include `type` (`user`, `agent`, `tool`, or `system`) plus `actor_id`, so chat views
can distinguish Telegram users from APX agents and future subagents.
A **channel** is the surface a turn arrived on. The canonical list lives in
`src/core/constants/channels.js`; `voice` is a *mode*, not a channel.
| Channel | What it captures |
|---------|-----------------|
| `cli` | `apx exec` / `apx run` from the terminal |
| `telegram` | Telegram bot messages |
| `api` | Direct daemon HTTP calls |
| `web` | The admin panel's main chat |
| `web_sidebar` | The panel's side assistant |
| `web_code` | The panel's coding surface |
| `code` | `apx code` sessions |
| `deck` | The tablet/phone dashboard |
| `desktop` | The floating voice capsule (always voice mode) |
| `routine` | Scheduled routine runs |
## Runtimes
| Runtime | Description |
|---------|-------------|
| `claude-code` | Spawns Claude Code CLI with the agent's system prompt injected |
| `codex` | OpenAI Codex CLI via non-interactive `codex exec --sandbox workspace-write --skip-git-repo-check` |
| `opencode` | OpenCode CLI |
| `aider` | Aider CLI |
| `cursor-agent` | Cursor's headless agent |
| `gemini-cli` | Google Gemini CLI |
| `qwen-code` | Qwen Code CLI |
| `antigravity` | Antigravity CLI |
Global APX skill installation also writes named helper skills for `codex-cli`, `claude-code`,
`opencode-cli`, and `openrouter`. They are intentionally narrow and should activate only when those
tools/providers are explicitly mentioned.
## Engines (for `apx exec`)
Configured in `~/.apx/config.json`:
```json
{
"engines": {
"anthropic": { "api_key": "sk-ant-..." },
"openai": { "api_key": "sk-..." },
"ollama": { "base_url": "http://localhost:11434" },
"gemini": { "api_key": "..." }
}
}
```
## Architecture
<p align="center">
<img src="assets/diagram.png" alt="APX architecture diagram" width="720">
</p>
## APC protocol
APX implements the [APC specification](https://github.com/agentprojectcontext/agentprojectcontext). The spec defines the on-disk layout; APX provides the tooling to use it.
## Community
Questions, what other people are wiring up, and where new releases land first:
**[discord.gg/vxdZuT5WuE](https://discord.gg/vxdZuT5WuE)**
## License
MIT
连接信息
猜你喜欢
暂无推荐服务器