anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-24 20:25:36 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

refactor: remove hardcoded paths and add upstream merge protection

Browse Source 
Code changes:
- Add Global.Path.source getter with AGENT_CORE_SOURCE env var support
- Update status.ts to use Global.Path.source for script paths
- Update setup.ts to use Global.Path.source for docker-compose lookup

Documentation updates:
- Remove hardcoded ~/.local/src/agent-core paths from all docs
- Use generic or relative path references throughout
- README.md, CLAUDE.md, OPS.md, USER_GUIDE.md, PROVIDERS.md updated

Upstream merge protection:
- Add .gitattributes with merge=ours for fork-specific files
- Configure ours merge driver
- Protects: README.md, CONTRIBUTING.md, CLAUDE.md, language READMEs, docs

Deleted (fork cleanup):
- README.zh-CN.md (Chinese Simplified)
- README.zh-TW.md (Chinese Traditional)
- CONTRIBUTING.md
This commit is contained in:
Artur Do Lago
2026-01-13 10:35:29 +01:00
parent b43df2b888
commit 0aa693ba3f
12 changed files with 101 additions and 513 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitattributes
+19
View File
@@ -0,0 +1,19 @@
# Files to preserve during upstream merges (use "ours" strategy)
# These are fork-specific customizations that should not be overwritten
# Fork-specific documentation
README.md merge=ours
CONTRIBUTING.md merge=ours
CLAUDE.md merge=ours
# Non-English READMEs (removed from this fork)
README.zh-CN.md merge=ours
README.zh-TW.md merge=ours
# Fork-specific configuration
.agent-core/agent-core.jsonc merge=ours
# Fork customizations in docs
docs/OPS.md merge=ours
docs/USER_GUIDE.md merge=ours
docs/PROVIDERS.md merge=ours
CLAUDE.md
+4 -4
View File
@@ -254,9 +254,9 @@ This system has experimental features enabled:
### Repository Location
**Source code:** `~/.local/src/agent-core`
**Source code:** The project root (can be customized via `AGENT_CORE_SOURCE` env var)
This hidden location prevents accidentally running from the repo directory (which can cause config confusion).
By default, the canonical location is `~/.local/src/agent-core`, but the project can be cloned anywhere.
### Binary Location
@@ -283,11 +283,11 @@ This hidden location prevents accidentally running from the repo directory (whic
```bash
# Build from repo
cd ~/.local/src/agent-core/packages/agent-core && bun run build
cd packages/agent-core && bun run build
# Kill running instances and install (MUST close TUI first)
pkill -f agent-core; sleep 1
cp ~/.local/src/agent-core/packages/agent-core/dist/agent-core-linux-x64/bin/agent-core ~/bin/agent-core
cp packages/agent-core/dist/agent-core-linux-x64/bin/agent-core ~/bin/agent-core
```
### Common Processes
CONTRIBUTING.md
-225
View File
@@ -1,225 +0,0 @@
# Contributing to OpenCode
We want to make it easy for you to contribute to OpenCode. Here are the most common type of changes that get merged:
- Bug fixes
- Additional LSPs / Formatters
- Improvements to LLM performance
- Support for new providers
- Fixes for environment-specific quirks
- Missing standard behavior
- Documentation improvements
However, any UI or core product feature must go through a design review with the core team before implementation.
If you are unsure if a PR would be accepted, feel free to ask a maintainer or look for issues with any of the following labels:
- [`help wanted`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3Ahelp-wanted)
- [`good first issue`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
- [`bug`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug)
- [`perf`](https://github.com/anomalyco/opencode/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22perf%22)
> [!NOTE]
> PRs that ignore these guardrails will likely be closed.
Want to take on an issue? Leave a comment and a maintainer may assign it to you unless it is something we are already working on.
## Developing OpenCode
- Requirements: Bun 1.3+
- Install dependencies and start the dev server from the repo root:
```bash
bun install
bun dev
```
### Running against a different directory
By default, `bun dev` runs OpenCode in the `packages/agent-core` directory. To run it against a different directory or repository:
```bash
bun dev <directory>
```
To run OpenCode in the root of the opencode repo itself:
```bash
bun dev .
```
### Building a "localcode"
To compile a standalone executable:
```bash
./packages/agent-core/script/build.ts --single
```
Then run it with:
```bash
./packages/agent-core/dist/opencode-<platform>/bin/opencode
```
Replace `<platform>` with your platform (e.g., `darwin-arm64`, `linux-x64`).
- Core pieces:
- `packages/agent-core`: OpenCode core business logic & server.
- `packages/agent-core/src/cli/cmd/tui/`: The TUI code, written in SolidJS with [opentui](https://github.com/sst/opentui)
- `packages/app`: The shared web UI components, written in SolidJS
- `packages/desktop`: The native desktop app, built with Tauri (wraps `packages/app`)
- `packages/plugin`: Source for `@opencode-ai/plugin`
### Running the Web App
To test UI changes during development, run the web app:
```bash
bun run --cwd packages/app dev
```
This starts a local dev server at http://localhost:5173 (or similar port shown in output). Most UI changes can be tested here.
### Running the Desktop App
The desktop app is a native Tauri application that wraps the web UI.
To run the native desktop app:
```bash
bun run --cwd packages/desktop tauri dev
```
This starts the web dev server on http://localhost:1420 and opens the native window.
If you only want the web dev server (no native shell):
```bash
bun run --cwd packages/desktop dev
```
To create a production `dist/` and build the native app bundle:
```bash
bun run --cwd packages/desktop tauri build
```
This runs `bun run --cwd packages/desktop build` automatically via Tauri’s `beforeBuildCommand`.
> [!NOTE]
> Running the desktop app requires additional Tauri dependencies (Rust toolchain, platform-specific libraries). See the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) for setup instructions.
> [!NOTE]
> If you make changes to the API or SDK (e.g. `packages/agent-core/src/server/server.ts`), run `./script/generate.ts` to regenerate the SDK and related files.
Please try to follow the [style guide](./STYLE_GUIDE.md)
### Setting up a Debugger
Bun debugging is currently rough around the edges. We hope this guide helps you get set up and avoid some pain points.
The most reliable way to debug OpenCode is to run it manually in a terminal via `bun run --inspect=<url> dev ...` and attach
your debugger via that URL. Other methods can result in breakpoints being mapped incorrectly, at least in VSCode (YMMV).
Caveats:
- If you want to run the OpenCode TUI and have breakpoints triggered in the server code, you might need to run `bun dev spawn` instead of
the usual `bun dev`. This is because `bun dev` runs the server in a worker thread and breakpoints might not work there.
- If `spawn` does not work for you, you can debug the server separately:
- Debug server: `bun run --inspect=ws://localhost:6499/ ./src/index.ts serve --port 4096`,
then attach TUI with `opencode attach http://localhost:4096`
- Debug TUI: `bun run --inspect=ws://localhost:6499/ --conditions=browser ./src/index.ts`
Other tips and tricks:
- You might want to use `--inspect-wait` or `--inspect-brk` instead of `--inspect`, depending on your workflow
- Specifying `--inspect=ws://localhost:6499/` on every invocation can be tiresome, you may want to `export BUN_OPTIONS=--inspect=ws://localhost:6499/` instead
#### VSCode Setup
If you use VSCode, you can use our example configurations [.vscode/settings.example.json](.vscode/settings.example.json) and [.vscode/launch.example.json](.vscode/launch.example.json).
Some debug methods that can be problematic:
- Debug configurations with `"request": "launch"` can have breakpoints incorrectly mapped and thus unusable
- The same problem arises when running OpenCode in the VSCode `JavaScript Debug Terminal`
With that said, you may want to try these methods, as they might work for you.
## Pull Request Expectations
### Issue First Policy
**All PRs must reference an existing issue.** Before opening a PR, open an issue describing the bug or feature. This helps maintainers triage and prevents duplicate work. PRs without a linked issue may be closed without review.
- Use `Fixes #123` or `Closes #123` in your PR description to link the issue
- For small fixes, a brief issue is fine - just enough context for maintainers to understand the problem
### General Requirements
- Keep pull requests small and focused
- Explain the issue and why your change fixes it
- Before adding new functionality, ensure it doesn't already exist elsewhere in the codebase
### UI Changes
If your PR includes UI changes, please include screenshots or videos showing the before and after. This helps maintainers review faster and gives you quicker feedback.
### Logic Changes
For non-UI changes (bug fixes, new features, refactors), explain **how you verified it works**:
- What did you test?
- How can a reviewer reproduce/confirm the fix?
### No AI-Generated Walls of Text
Long, AI-generated PR descriptions and issues are not acceptable and may be ignored. Respect the maintainers' time:
- Write short, focused descriptions
- Explain what changed and why in your own words
- If you can't explain it briefly, your PR might be too large
### PR Titles
PR titles should follow conventional commit standards:
- `feat:` new feature or functionality
- `fix:` bug fix
- `docs:` documentation or README changes
- `chore:` maintenance tasks, dependency updates, etc.
- `refactor:` code refactoring without changing behavior
- `test:` adding or updating tests
You can optionally include a scope to indicate which package is affected:
- `feat(app):` feature in the app package
- `fix(desktop):` bug fix in the desktop package
- `chore(opencode):` maintenance in the opencode package
Examples:
- `docs: update contributing guidelines`
- `fix: resolve crash on startup`
- `feat: add dark mode support`
- `feat(app): add dark mode support`
- `fix(desktop): resolve crash on startup`
- `chore: bump dependency versions`
### Style Preferences
These are not strictly enforced, they are just general guidelines:
- **Functions:** Keep logic within a single function unless breaking it out adds clear reuse or composition benefits.
- **Destructuring:** Do not do unnecessary destructuring of variables.
- **Control flow:** Avoid `else` statements.
- **Error handling:** Prefer `.catch(...)` instead of `try`/`catch` when possible.
- **Types:** Reach for precise types and avoid `any`.
- **Variables:** Stick to immutable patterns and avoid `let`.
- **Naming:** Choose concise single-word identifiers when they remain descriptive.
- **Runtime APIs:** Use Bun helpers such as `Bun.file()` when they fit the use case.
## Feature Requests
For net-new functionality, start with a design conversation. Open an issue describing the problem, your proposed approach (optional), and why it belongs in OpenCode. The core team will help decide whether it should move forward; please wait for that approval instead of opening a feature PR directly.
README.md
+12 -8
View File
@@ -19,10 +19,10 @@ Agent-Core is a CLI agent engine that powers the Personas system (Zee, Stanley,
```bash
# Clone the repository
git clone https://github.com/yourusername/agent-core.git ~/.local/src/agent-core
git clone https://github.com/yourusername/agent-core.git
# Install dependencies
cd ~/.local/src/agent-core
cd agent-core
bun install
# Build the project
@@ -36,11 +36,13 @@ cp dist/agent-core-linux-x64/bin/agent-core ~/bin/agent-core
### Configuration
1. Copy the environment template:
```bash
cp .env.example .env
```
2. Edit `.env` and add your API keys:
```bash
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-... # For embeddings
@@ -48,6 +50,7 @@ QDRANT_URL=http://localhost:6333
```
3. Start Qdrant (if running locally):
```bash
docker run -p 6333:6333 qdrant/qdrant
```
@@ -55,11 +58,12 @@ docker run -p 6333:6333 qdrant/qdrant
### Running
**Interactive TUI:**
```bash
agent-core
```
**Daemon mode (for Zee gateway):**
**Daemon mode (for external gateways):**
```bash
agent-core daemon --gateway --hostname 127.0.0.1 --port 3210
```
@@ -80,11 +84,11 @@ agent-core/
### Personas
| Persona | Domain | Description |
|---------|--------|-------------|
| **Zee** | Personal Assistant | Memory, messaging, calendar, notifications |
| **Stanley** | Investing | Markets, portfolio, trading strategies |
| **Johny** | Learning | Knowledge graphs, spaced repetition |
| Persona | Domain | Description |
| ----------- | ------------------ | ------------------------------------------ |
| **Zee** | Personal Assistant | Memory, messaging, calendar, notifications |
| **Stanley** | Investing | Markets, portfolio, trading strategies |
| **Johny** | Learning | Knowledge graphs, spaced repetition |
### Key Features
README.zh-CN.md
-118
View File
@@ -1,118 +0,0 @@
<p align="center">
<a href="https://opencode.ai">
<picture>
<source srcset="packages/console/app/src/asset/logo-ornate-dark.svg" media="(prefers-color-scheme: dark)">
<source srcset="packages/console/app/src/asset/logo-ornate-light.svg" media="(prefers-color-scheme: light)">
<img src="packages/console/app/src/asset/logo-ornate-light.svg" alt="OpenCode logo">
</picture>
</a>
</p>
<p align="center">开源的 AI Coding Agent。</p>
<p align="center">
<a href="https://opencode.ai/discord"><img alt="Discord" src="https://img.shields.io/discord/1391832426048651334?style=flat-square&label=discord" /></a>
<a href="https://www.npmjs.com/package/opencode-ai"><img alt="npm" src="https://img.shields.io/npm/v/opencode-ai?style=flat-square" /></a>
<a href="https://github.com/anomalyco/opencode/actions/workflows/publish.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/anomalyco/opencode/publish.yml?style=flat-square&branch=dev" /></a>
</p>
[![OpenCode Terminal UI](packages/web/src/assets/lander/screenshot.png)](https://opencode.ai)
---
### 安装
```bash
# 直接安装 (YOLO)
curl -fsSL https://opencode.ai/install | bash
# 软件包管理器
npm i -g opencode-ai@latest # 也可使用 bun/pnpm/yarn
scoop install opencode # Windows
choco install opencode # Windows
brew install anomalyco/tap/opencode # macOS 和 Linux（推荐，始终保持最新）
brew install opencode # macOS 和 Linux（官方 brew formula，更新频率较低）
paru -S opencode-bin # Arch Linux
mise use -g opencode # 任意系统
nix run nixpkgs#opencode # 或用 github:anomalyco/opencode 获取最新 dev 分支
```
> [!TIP]
> 安装前请先移除 0.1.x 之前的旧版本。
### 桌面应用程序 (BETA)
OpenCode 也提供桌面版应用。可直接从 [发布页 (releases page)](https://github.com/anomalyco/opencode/releases) 或 [opencode.ai/download](https://opencode.ai/download) 下载。
| 平台 | 下载文件 |
| --------------------- | ------------------------------------- |
| macOS (Apple Silicon) | `opencode-desktop-darwin-aarch64.dmg` |
| macOS (Intel) | `opencode-desktop-darwin-x64.dmg` |
| Windows | `opencode-desktop-windows-x64.exe` |
| Linux | `.deb`、`.rpm` 或 AppImage |
```bash
# macOS (Homebrew Cask)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop
```
#### 安装目录
安装脚本按照以下优先级决定安装路径：
1. `$OPENCODE_INSTALL_DIR` - 自定义安装目录
2. `$XDG_BIN_DIR` - 符合 XDG 基础目录规范的路径
3. `$HOME/bin` - 如果存在或可创建的用户二进制目录
4. `$HOME/.opencode/bin` - 默认备用路径
```bash
# 示例
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash
```
### Agents
OpenCode 内置两种 Agent，可用 `Tab` 键快速切换：
- **build** - 默认模式，具备完整权限，适合开发工作
- **plan** - 只读模式，适合代码分析与探索
- 默认拒绝修改文件
- 运行 bash 命令前会询问
- 便于探索未知代码库或规划改动
另外还包含一个 **general** 子 Agent，用于复杂搜索和多步任务，内部使用，也可在消息中输入 `@general` 调用。
了解更多 [Agents](https://opencode.ai/docs/agents) 相关信息。
### 文档
更多配置说明请查看我们的 [**官方文档**](https://opencode.ai/docs)。
### 参与贡献
如有兴趣贡献代码，请在提交 PR 前阅读 [贡献指南 (Contributing Docs)](./CONTRIBUTING.md)。
### 基于 OpenCode 进行开发
如果你在项目名中使用了 “opencode”（如 “opencode-dashboard” 或 “opencode-mobile”），请在 README 里注明该项目不是 OpenCode 团队官方开发，且不存在隶属关系。
### 常见问题 (FAQ)
#### 这和 Claude Code 有什么不同？
功能上很相似，关键差异：
- 100% 开源。
- 不绑定特定提供商。推荐使用 [OpenCode Zen](https://opencode.ai/zen) 的模型，但也可搭配 Claude、OpenAI、Google 甚至本地模型。模型迭代会缩小差异、降低成本，因此保持 provider-agnostic 很重要。
- 内置 LSP 支持。
- 聚焦终端界面 (TUI)。OpenCode 由 Neovim 爱好者和 [terminal.shop](https://terminal.shop) 的创建者打造，会持续探索终端的极限。
- 客户端/服务器架构。可在本机运行，同时用移动设备远程驱动。TUI 只是众多潜在客户端之一。
#### 另一个同名的仓库是什么？
另一个名字相近的仓库与本项目无关。[点击这里了解背后故事](https://x.com/thdxr/status/1933561254481666466)。
---
**加入我们的社区** [Discord](https://discord.gg/opencode) | [X.com](https://x.com/opencode)
README.zh-TW.md
-118
View File
@@ -1,118 +0,0 @@
<p align="center">
<a href="https://opencode.ai">
<picture>
<source srcset="packages/console/app/src/asset/logo-ornate-dark.svg" media="(prefers-color-scheme: dark)">
<source srcset="packages/console/app/src/asset/logo-ornate-light.svg" media="(prefers-color-scheme: light)">
<img src="packages/console/app/src/asset/logo-ornate-light.svg" alt="OpenCode logo">
</picture>
</a>
</p>
<p align="center">開源的 AI Coding Agent。</p>
<p align="center">
<a href="https://opencode.ai/discord"><img alt="Discord" src="https://img.shields.io/discord/1391832426048651334?style=flat-square&label=discord" /></a>
<a href="https://www.npmjs.com/package/opencode-ai"><img alt="npm" src="https://img.shields.io/npm/v/opencode-ai?style=flat-square" /></a>
<a href="https://github.com/anomalyco/opencode/actions/workflows/publish.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/anomalyco/opencode/publish.yml?style=flat-square&branch=dev" /></a>
</p>
[![OpenCode Terminal UI](packages/web/src/assets/lander/screenshot.png)](https://opencode.ai)
---
### 安裝
```bash
# 直接安裝 (YOLO)
curl -fsSL https://opencode.ai/install | bash
# 套件管理員
npm i -g opencode-ai@latest # 也可使用 bun/pnpm/yarn
scoop install opencode # Windows
choco install opencode # Windows
brew install anomalyco/tap/opencode # macOS 與 Linux（推薦，始終保持最新）
brew install opencode # macOS 與 Linux（官方 brew formula，更新頻率較低）
paru -S opencode-bin # Arch Linux
mise use -g github:anomalyco/opencode # 任何作業系統
nix run nixpkgs#opencode # 或使用 github:anomalyco/opencode 以取得最新開發分支
```
> [!TIP]
> 安裝前請先移除 0.1.x 以前的舊版本。
### 桌面應用程式 (BETA)
OpenCode 也提供桌面版應用程式。您可以直接從 [發佈頁面 (releases page)](https://github.com/anomalyco/opencode/releases) 或 [opencode.ai/download](https://opencode.ai/download) 下載。
| 平台 | 下載連結 |
| --------------------- | ------------------------------------- |
| macOS (Apple Silicon) | `opencode-desktop-darwin-aarch64.dmg` |
| macOS (Intel) | `opencode-desktop-darwin-x64.dmg` |
| Windows | `opencode-desktop-windows-x64.exe` |
| Linux | `.deb`, `.rpm`, 或 AppImage |
```bash
# macOS (Homebrew Cask)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop
```
#### 安裝目錄
安裝腳本會依據以下優先順序決定安裝路徑：
1. `$OPENCODE_INSTALL_DIR` - 自定義安裝目錄
2. `$XDG_BIN_DIR` - 符合 XDG 基礎目錄規範的路徑
3. `$HOME/bin` - 標準使用者執行檔目錄 (若存在或可建立)
4. `$HOME/.opencode/bin` - 預設備用路徑
```bash
# 範例
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash
```
### Agents
OpenCode 內建了兩種 Agent，您可以使用 `Tab` 鍵快速切換。
- **build** - 預設模式，具備完整權限的 Agent，適用於開發工作。
- **plan** - 唯讀模式，適用於程式碼分析與探索。
- 預設禁止修改檔案。
- 執行 bash 指令前會詢問權限。
- 非常適合用來探索陌生的程式碼庫或規劃變更。
此外，OpenCode 還包含一個 **general** 子 Agent，用於處理複雜搜尋與多步驟任務。此 Agent 供系統內部使用，亦可透過在訊息中輸入 `@general` 來呼叫。
了解更多關於 [Agents](https://opencode.ai/docs/agents) 的資訊。
### 線上文件
關於如何設定 OpenCode 的詳細資訊，請參閱我們的 [**官方文件**](https://opencode.ai/docs)。
### 參與貢獻
如果您有興趣參與 OpenCode 的開發，請在提交 Pull Request 前先閱讀我們的 [貢獻指南 (Contributing Docs)](./CONTRIBUTING.md)。
### 基於 OpenCode 進行開發
如果您正在開發與 OpenCode 相關的專案，並在名稱中使用了 "opencode"（例如 "opencode-dashboard" 或 "opencode-mobile"），請在您的 README 中加入聲明，說明該專案並非由 OpenCode 團隊開發，且與我們沒有任何隸屬關係。
### 常見問題 (FAQ)
#### 這跟 Claude Code 有什麼不同？
在功能面上與 Claude Code 非常相似。以下是關鍵差異：
- 100% 開源。
- 不綁定特定的服務提供商。雖然我們推薦使用透過 [OpenCode Zen](https://opencode.ai/zen) 提供的模型，但 OpenCode 也可搭配 Claude, OpenAI, Google 甚至本地模型使用。隨著模型不斷演進，彼此間的差距會縮小且價格會下降，因此具備「不限廠商 (provider-agnostic)」的特性至關重要。
- 內建 LSP (語言伺服器協定) 支援。
- 專注於終端機介面 (TUI)。OpenCode 由 Neovim 愛好者與 [terminal.shop](https://terminal.shop) 的創作者打造；我們將不斷挑戰終端機介面的極限。
- 客戶端/伺服器架構 (Client/Server Architecture)。這讓 OpenCode 能夠在您的電腦上運行的同時，由行動裝置進行遠端操控。這意味著 TUI 前端只是眾多可能的客戶端之一。
#### 另一個同名的 Repo 是什麼？
另一個名稱相近的儲存庫與本專案無關。您可以點此[閱讀背後的故事](https://x.com/thdxr/status/1933561254481666466)。
---
**加入我們的社群** [Discord](https://discord.gg/opencode) | [X.com](https://x.com/opencode)
docs/OPS.md
+14 -14
View File
@@ -20,7 +20,7 @@
### 1. Development Mode (`bun run dev`)
```bash
cd ~/.local/src/agent-core/packages/agent-core
cd packages/agent-core
bun run dev --print-logs
```
@@ -66,7 +66,7 @@ pgrep -af "/bin/agent-core"
│ WHY FIXES DON'T TAKE EFFECT │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ You edit: ~/.local/src/agent-core/packages/agent-core/src/foo.ts │
│ You edit: packages/agent-core/src/foo.ts │
│ │
│ BUT your TUI is running: │
│ │
@@ -99,7 +99,7 @@ pgrep -af "/bin/agent-core"
## The Reload Script
Located at: `~/.local/src/agent-core/scripts/reload.sh`
Located at: `./scripts/reload.sh` (from project root)
### What It Does
@@ -199,7 +199,7 @@ When a fix doesn't take effect, check in order:
- [ ] **4. When was the source file modified?**
```bash
ls -la ~/.local/src/agent-core/packages/agent-core/src/path/to/file.ts
ls -la packages/agent-core/src/path/to/file.ts
```
- [ ] **5. Is source newer than binary?**
@@ -215,16 +215,16 @@ When a fix doesn't take effect, check in order:
## Location Reference
| What | Path |
| ----------------- | -------------------------------------------------------------------------------------- |
| Source repository | `~/.local/src/agent-core` |
| Package source | `~/.local/src/agent-core/packages/agent-core/src/` |
| Compiled binary | `~/bin/agent-core` |
| Build output | `~/.local/src/agent-core/packages/agent-core/dist/agent-core-linux-x64/bin/agent-core` |
| Reload script | `~/.local/src/agent-core/scripts/reload.sh` |
| Config directory | `~/.config/agent-core/` |
| Custom tools | `~/.config/agent-core/tool/` |
| Daemon logs | `/tmp/agent-core-daemon.log` |
| What | Path |
| ----------------- | -------------------------------------------------------------- |
| Source repository | Project root (or set `AGENT_CORE_SOURCE`) |
| Package source | `packages/agent-core/src/` |
| Compiled binary | `~/bin/agent-core` |
| Build output | `packages/agent-core/dist/agent-core-linux-x64/bin/agent-core` |
| Reload script | `./scripts/reload.sh` |
| Config directory | `~/.config/agent-core/` |
| Custom tools | `~/.config/agent-core/tool/` |
| Daemon logs | `/tmp/agent-core-daemon.log` |
## MCP Servers Note
docs/PROVIDERS.md
+20 -18
View File
@@ -4,12 +4,12 @@ This document describes the working provider setup for agent-core.
## Config Locations
| Type | Location |
|------|----------|
| Project config | `~/.local/src/agent-core/.agent-core/agent-core.jsonc` |
| Global config (symlink) | `~/.config/agent-core/agent-core.jsonc` |
| Agent definitions | `~/.local/src/agent-core/.agent-core/agent/` |
| Global agents (symlink) | `~/.config/agent-core/agent/` |
| Type | Location |
| ----------------------- | ------------------------------------------------ |
| Project config | `.agent-core/agent-core.jsonc` (in project root) |
| Global config (symlink) | `~/.config/agent-core/agent-core.jsonc` |
| Agent definitions | `.agent-core/agent/` (in project root) |
| Global agents (symlink) | `~/.config/agent-core/agent/` |
The global config is symlinked to project config so changes in one location reflect in both.
@@ -31,6 +31,7 @@ Free-tier models via the `opencode-antigravity-auth` plugin.
| `google/antigravity-gemini-3-flash` | Gemini 3 Flash | Fast |
**Notes:**
- Models are hardcoded in `provider.ts` and auto-loaded when the antigravity plugin detects auth
- Opus 4.5 is only available as the `-thinking` variant
- Thinking models require `topP >= 0.95` (handled automatically by ProviderTransform)
@@ -57,26 +58,27 @@ Access to various models including Grok, Llama, etc.
## Disabled Providers
These are disabled in `agent-core.jsonc`:
- `google-vertex` - Direct Vertex AI (redundant with Antigravity)
- `google-vertex-anthropic` - Vertex Claude (redundant with Antigravity)
## Agent Defaults
| Agent | Default Model | Purpose |
|-------|---------------|---------|
| Zee | `cerebras/zai-glm-4.7` | Personal assistant |
| Stanley | `openrouter/x-ai/grok-4.1-fast` | Investing assistant |
| Johny | `google/antigravity-claude-opus-4-5-thinking` | Learning assistant |
| title | `cerebras/gpt-oss-120b` | Conversation titles (hidden) |
| compaction | `google/antigravity-gemini-3-flash` | Context compaction (hidden) |
| Agent | Default Model | Purpose |
| ---------- | --------------------------------------------- | ---------------------------- |
| Zee | `cerebras/zai-glm-4.7` | Personal assistant |
| Stanley | `openrouter/x-ai/grok-4.1-fast` | Investing assistant |
| Johny | `google/antigravity-claude-opus-4-5-thinking` | Learning assistant |
| title | `cerebras/gpt-oss-120b` | Conversation titles (hidden) |
| compaction | `google/antigravity-gemini-3-flash` | Context compaction (hidden) |
## Auth Storage
| Provider | Auth Location | Type |
|----------|---------------|------|
| Google (Antigravity) | `~/.local/share/agent-core/auth.json` under `google` key | OAuth |
| Cerebras | Environment variable | API Key |
| OpenRouter | Environment variable | API Key |
| Provider | Auth Location | Type |
| -------------------- | -------------------------------------------------------- | ------- |
| Google (Antigravity) | `~/.local/share/agent-core/auth.json` under `google` key | OAuth |
| Cerebras | Environment variable | API Key |
| OpenRouter | Environment variable | API Key |
## Adding New Models
docs/USER_GUIDE.md
+24 -3
View File
@@ -6,16 +6,18 @@ This guide will get you from "zero" to "fully operational AI assistant".
## 1. Installation
### Prerequisites
- **Docker Desktop** (or Docker Engine + Compose)
- **Bun** (v1.1+) or Node.js
### Install
```bash
# Clone the repo
git clone https://github.com/yourusername/agent-core.git ~/.local/src/agent-core
git clone https://github.com/yourusername/agent-core.git
# Install dependencies and build
cd ~/.local/src/agent-core
cd agent-core
./install
```
@@ -28,6 +30,7 @@ agent-core setup
```
This will:
1. Check for Docker.
2. Spin up the Qdrant database container.
3. Verify connection.
@@ -35,15 +38,19 @@ This will:
## 3. Configuration
### Authentication
You need an LLM provider (Anthropic is recommended for best results).
```bash
agent-core auth login
```
Select "Anthropic" or "OpenAI" and paste your API key.
### Personas
Agent-Core comes with three built-in personas:
- **Zee:** Your personal assistant (Calendar, Tasks, Memory).
- **Stanley:** Financial research (requires the `stanley` repository).
- **Johny:** Learning and Knowledge graphs.
@@ -51,14 +58,19 @@ Agent-Core comes with three built-in personas:
## 4. Usage
### Interactive Mode (TUI)
Start the Terminal User Interface:
```bash
agent-core
```
Type your request. For example:
> "Zee, remind me to check the server logs tomorrow at 9am."
### Using Personas
You can route requests to specific personas:
> "Stanley, what is the P/E ratio of NVDA?"
@@ -66,6 +78,7 @@ You can route requests to specific personas:
> "Johny, explain the concept of eigenvectors."
### Daemon Mode
To run Agent-Core in the background (required for external tools like the Mobile App or WhatsApp gateway):
```bash
@@ -75,27 +88,35 @@ agent-core daemon
## 5. Troubleshooting
### Diagnostics
If something isn't working:
```bash
agent-core debug status
```
### Bug Report
To generate a zip file with logs for support:
```bash
agent-core bug-report
```
### Logs
Logs are stored in `~/.local/state/agent-core/logs/`.
The system keeps the last 5 sessions automatically.
## 6. Advanced: Connecting Stanley
To unlock the full power of the Investment Persona:
1. Clone the Stanley repo to `~/Repositories/personas/stanley`.
2. Set up the Python environment there (`pip install -r requirements.txt`).
3. Agent-Core will automatically detect the CLI.
Run `agent-core` and ask:
> "Stanley, status"
To verify the connection.
> To verify the connection.
packages/agent-core/src/cli/cmd/debug/status.ts
+3 -3
View File
@@ -192,7 +192,7 @@ async function collectStatus(verbose: boolean): Promise<SystemStatus> {
// Check source file timestamps (for rebuild detection)
if (verbose && status.binary.modifiedTs) {
const srcRoot = path.join(process.env.HOME || "", ".local", "src", "agent-core", "packages", "agent-core", "src")
const srcRoot = path.join(Global.Path.source, "packages", "agent-core", "src")
const keyFiles = ["provider/transform.ts", "provider/provider.ts", "server/server.ts"]
for (const file of keyFiles) {
@@ -343,10 +343,10 @@ function printStatus(status: SystemStatus, verbose: boolean) {
console.log("")
console.log(`${BLUE}Quick fixes:${RESET}`)
if (status.issues.some((i) => i.includes("rebuild"))) {
console.log(" Rebuild: ~/.local/src/agent-core/scripts/reload.sh")
console.log(` Rebuild: ${Global.Path.source}/scripts/reload.sh`)
}
if (status.issues.some((i) => i.includes("restart"))) {
console.log(" Restart: ~/.local/src/agent-core/scripts/reload.sh --no-build")
console.log(` Restart: ${Global.Path.source}/scripts/reload.sh --no-build`)
}
}
}
packages/agent-core/src/cli/cmd/setup.ts
+2 -2
View File
@@ -28,11 +28,11 @@ export const SetupCommand = cmd({
UI.success("Docker is running.")
// 2. Locate docker-compose.yml
// We expect it in the project root or ~/.local/src/agent-core/
// We expect it in the project root or Global.Path.source
// Since this is running from compiled code potentially, we look in known locations or cwd
const candidates = [
path.join(process.cwd(), "docker-compose.yml"),
path.join(Global.Path.home, ".local/src/agent-core/docker-compose.yml"),
path.join(Global.Path.source, "docker-compose.yml"),
// If we are in the source tree:
path.resolve(__dirname, "../../../../../docker-compose.yml"),
]
packages/agent-core/src/global/index.ts
+3
View File
@@ -25,6 +25,9 @@ export namespace Global {
get home() {
return process.env.AGENT_CORE_TEST_HOME || process.env.OPENCODE_TEST_HOME || os.homedir()
},
get source() {
return process.env.AGENT_CORE_SOURCE || path.join(this.home, ".local", "src", "agent-core")
},
get data() {
return path.join(getXdgDataHome(), app)
},