From 0aa693ba3fb6b17c03307f00fbcc934757f4aa91 Mon Sep 17 00:00:00 2001 From: Artur Do Lago Date: Tue, 13 Jan 2026 10:35:29 +0100 Subject: [PATCH] refactor: remove hardcoded paths and add upstream merge protection 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 --- .gitattributes | 19 ++ CLAUDE.md | 8 +- CONTRIBUTING.md | 225 ------------------ README.md | 20 +- README.zh-CN.md | 118 --------- README.zh-TW.md | 118 --------- docs/OPS.md | 28 +-- docs/PROVIDERS.md | 38 +-- docs/USER_GUIDE.md | 27 ++- .../agent-core/src/cli/cmd/debug/status.ts | 6 +- packages/agent-core/src/cli/cmd/setup.ts | 4 +- packages/agent-core/src/global/index.ts | 3 + 12 files changed, 101 insertions(+), 513 deletions(-) create mode 100644 .gitattributes delete mode 100644 CONTRIBUTING.md delete mode 100644 README.zh-CN.md delete mode 100644 README.zh-TW.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000000..3bec04f6031 --- /dev/null +++ b/.gitattributes @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index fb4b7c50343..7fbd3d7a387 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index a97315f300e..00000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -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 -``` - -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-/bin/opencode -``` - -Replace `` 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= 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. diff --git a/README.md b/README.md index f972b36194d..c52f7c4c20d 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README.zh-CN.md b/README.zh-CN.md deleted file mode 100644 index 4b56e0fb0b0..00000000000 --- a/README.zh-CN.md +++ /dev/null @@ -1,118 +0,0 @@ -

- - - - - OpenCode logo - - -

-

开源的 AI Coding Agent。

-

- Discord - npm - Build status -

- -[![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) diff --git a/README.zh-TW.md b/README.zh-TW.md deleted file mode 100644 index 66664a70305..00000000000 --- a/README.zh-TW.md +++ /dev/null @@ -1,118 +0,0 @@ -

- - - - - OpenCode logo - - -

-

開源的 AI Coding Agent。

-

- Discord - npm - Build status -

- -[![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) diff --git a/docs/OPS.md b/docs/OPS.md index 2f28f7b2c0d..1eaf62c0c81 100644 --- a/docs/OPS.md +++ b/docs/OPS.md @@ -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 diff --git a/docs/PROVIDERS.md b/docs/PROVIDERS.md index fa7690f9dd6..7c9a482c0be 100644 --- a/docs/PROVIDERS.md +++ b/docs/PROVIDERS.md @@ -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 diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 875e4878c3f..23385d3e261 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -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. diff --git a/packages/agent-core/src/cli/cmd/debug/status.ts b/packages/agent-core/src/cli/cmd/debug/status.ts index 1d794cf5e96..0db7dbb0b53 100644 --- a/packages/agent-core/src/cli/cmd/debug/status.ts +++ b/packages/agent-core/src/cli/cmd/debug/status.ts @@ -192,7 +192,7 @@ async function collectStatus(verbose: boolean): Promise { // 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`) } } } diff --git a/packages/agent-core/src/cli/cmd/setup.ts b/packages/agent-core/src/cli/cmd/setup.ts index d15ad477db1..112ad748c3f 100644 --- a/packages/agent-core/src/cli/cmd/setup.ts +++ b/packages/agent-core/src/cli/cmd/setup.ts @@ -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"), ] diff --git a/packages/agent-core/src/global/index.ts b/packages/agent-core/src/global/index.ts index 191445e8f69..5ec0e38ecb5 100644 --- a/packages/agent-core/src/global/index.ts +++ b/packages/agent-core/src/global/index.ts @@ -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) },