# ai-workbase

**Repository Path**: KFCheems/ai-workbase

## Basic Information

- **Project Name**: ai-workbase
- **Description**: Cross-agent AI workbase for Codex, Claude Code, Trellis, and codedb.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KFCheems AI Workbase

This directory is the central workbase for local AI coding tools.

Purpose:
- Use one durable rule set across Codex, Claude Code, and other agents.
- Use codedb-mcp as the default source-code retrieval tool for initialized repos.
- Use Trellis as the main workflow system for non-trivial engineering work.
- Avoid indexing or initializing the whole `C:\WorkSpace` root.

Important files:
- `BASE.md`: global operating rules and product/repo analysis lens.
- `CODEDB.md`: codedb-mcp usage rules and project-scope constraints.
- `TRELLIS.md`: Trellis workflow rules.
- `CHANGELOG.md`: notable workbase changes.
- `install.mjs`: cross-platform installer for the workbase, Trellis, and codedb binary preparation.
- `scripts/bootstrap-unix.sh`: Linux/macOS system-level bootstrap.
- `scripts/Bootstrap-Workbase.ps1`: Windows system-level bootstrap.
- `scripts/dashboard.mjs`: local web dashboard for status, diagnostics, and safe actions.
- `scripts/doctor.mjs`: diagnostic report with actionable repair commands.
- `scripts/repair.mjs`: safe repair runner for missing workbase/project wiring.
- `scripts/prepare-task.mjs`: writes task-level Trellis+codedb context.
- `scripts/handoff.mjs`: writes `.trellis/workspace/handoff.md` so a new agent session can continue.
- `scripts/init-project.mjs`: cross-platform initializer for one concrete project.
- `scripts/Initialize-AIProject.ps1`: Windows compatibility wrapper around `scripts/init-project.mjs`.
- `scripts/install-codedb.mjs`: prepares codedb by reusing an existing binary or building `killop/codedb-mcp` from source with Cargo.
- `scripts/Show-WorkbaseStatus.ps1`: quick local status check.

Cross-platform quick start:

System-level bootstrap for a fresh machine:

Linux / macOS:

```bash
curl -fsSL https://gitee.com/KFCheems/ai-workbase/raw/master/scripts/bootstrap-unix.sh | bash -s -- /path/to/your-project
```

Windows PowerShell:

```powershell
irm https://gitee.com/KFCheems/ai-workbase/raw/master/scripts/Bootstrap-Workbase.ps1 | iex
```

To initialize a concrete project on Windows in the same run, download the script first so parameters can be passed safely:

```powershell
$script = "$env:TEMP\Bootstrap-Workbase.ps1"
irm https://gitee.com/KFCheems/ai-workbase/raw/master/scripts/Bootstrap-Workbase.ps1 -OutFile $script
powershell -NoProfile -ExecutionPolicy Bypass -File $script -ProjectRoot C:\path\to\your-project
```

The bootstrap scripts install or verify Git, Node.js 18+, Rust/Cargo, and build tools, then clone/update Workbase, run `node install.mjs`, and optionally initialize one concrete project. System package installation can still require `sudo`, macOS Xcode Command Line Tools confirmation, Windows UAC, or Visual Studio Build Tools installer confirmation.

Quick start when base dependencies already exist:

Linux:

```bash
sudo apt-get update
sudo apt-get install -y git curl build-essential
node --version
git clone https://gitee.com/KFCheems/ai-workbase.git ~/AI-Workbase
cd ~/AI-Workbase
node install.mjs
node ~/AI-Workbase/scripts/init-project.mjs /path/to/your-project
node ~/AI-Workbase/scripts/doctor.mjs /path/to/your-project
```

macOS:

```bash
brew install git node
git clone https://gitee.com/KFCheems/ai-workbase.git ~/AI-Workbase
cd ~/AI-Workbase
node install.mjs
node ~/AI-Workbase/scripts/init-project.mjs /path/to/your-project
node ~/AI-Workbase/scripts/doctor.mjs /path/to/your-project
```

Windows:

```powershell
winget install Git.Git OpenJS.NodeJS
git clone https://gitee.com/KFCheems/ai-workbase.git $env:USERPROFILE\AI-Workbase
cd $env:USERPROFILE\AI-Workbase
node install.mjs
node $env:USERPROFILE\AI-Workbase\scripts\init-project.mjs C:\path\to\your-project
node $env:USERPROFILE\AI-Workbase\scripts\doctor.mjs C:\path\to\your-project
```

Daily use on any platform:

```bash
node ~/AI-Workbase/scripts/init-project.mjs /path/to/your-project
```

On Windows, `scripts/Initialize-AIProject.ps1` is only a compatibility wrapper. The primary initializer is still `scripts/init-project.mjs`.

Do not run project initialization at a workspace container such as `C:\WorkSpace`, `~/Work`, or `~/projects` unless you intentionally want the entire workspace treated as one project. The script blocks common workspace containers by default.

Use with an AI agent:

```text
Use my AI workbase to initialize the current project:

https://gitee.com/KFCheems/ai-workbase.git

Requirements:
1. If the workbase is not installed, clone it to ~/AI-Workbase.
2. Run node install.mjs.
3. Initialize only the concrete project repository, not the whole workspace root.
4. Run node ~/AI-Workbase/scripts/init-project.mjs <current project root>.
5. Verify AGENTS.md, CLAUDE.md, .trellis, .codedb-mcp, and .codex/config.toml exist.
6. For Codex, verify project MCP and hooks; remind me to run /hooks if approval is needed.
7. Do not write any token into the repository, scripts, logs, or git remote.
```

Core commands:

```bash
git clone https://gitee.com/KFCheems/ai-workbase.git ~/AI-Workbase
cd ~/AI-Workbase
node install.mjs
node scripts/init-project.mjs /path/to/your-project
```

After initialization, new Codex or Claude Code conversations started inside that project can read the project entry files and continue from the Trellis/codedb structure.

Trellis + codedb alignment:

Project initialization writes a project-level work contract, not just files. It tells agents to read `AGENTS.md` / `CLAUDE.md`, use Trellis before substantial engineering work, inspect `.trellis/tasks/`, `.trellis/spec/`, and `.trellis/workspace/`, and confirm codedb is scoped to the current concrete repository before source lookup.

`doctor` checks more than file existence. It also verifies the project Trellis+codedb contract, the Codex codedb MCP root/config path, and that codedb storage stays under the project `.codedb-mcp` directory. If alignment is broken, rerun `node scripts/init-project.mjs <repo-root>` for that concrete repository.

Prepare task-level context before substantial work:

```bash
node scripts/prepare-task.mjs /path/to/your-project "fix login auth failure" --query auth --query login --file src/auth
```

This writes `.trellis/workspace/task-context.md`. It is the bridge between Trellis and codedb: read it before coding, use its `codedb_bundle` seed for initial retrieval, then store decisions and evidence back in Trellis or project docs.

Local dashboard:

```bash
node scripts/dashboard.mjs /path/to/your-project
```

Default URL:

```text
http://localhost:8765
```

The dashboard is localhost-only. It shows tool/global/project status and exposes only fixed safe actions: install/refresh global entries, initialize the current project, refresh codedb, update workbase, and run doctor. It does not expose arbitrary shell execution and strips common token/secret/password/key environment variables from child actions.

It also discovers Git projects under common workspace roots, so you can switch the active project without typing the full path each time.

The local config is stored outside this repository under the platform data directory. It can store search roots, favorite projects, recent projects, and explicit tool paths for Codex, Claude, Trellis, and Node when PATH detection is incomplete. The same data directory stores `projects-cache.json` for dashboard project discovery and `history.jsonl` for recent dashboard task history.

Project discovery and tool version checks use short-lived in-process caches so dashboard refreshes do not repeatedly scan large workspaces or rerun every `--version` command. Discovered projects are also persisted to `projects-cache.json`, so normal page loads can use the last known project list until you explicitly refresh the project cache.

The dashboard includes bulk project health checks with three depths: light checks workbase files, medium adds tool status, and deep adds codedb/Trellis workspace/handoff checks. You can select multiple discovered projects and run safe batch actions for project initialization, codedb refresh, or handoff generation.

Dashboard actions run as background tasks. The UI polls task output while commands run and can cancel the current task.

Completed, failed, and cancelled background actions are appended to `history.jsonl` with a compact output summary. The dashboard shows recent operation history next to the action log.

Doctor report:

```bash
node scripts/doctor.mjs /path/to/your-project
```

Safe repair:

```bash
node scripts/repair.mjs /path/to/your-project
```

Write a handoff note:

```bash
node scripts/handoff.mjs /path/to/your-project
```

Include the latest task-level codedb context in the handoff:

```bash
node scripts/handoff.mjs /path/to/your-project --with-codedb
```

Efficiency benchmark:

```bash
node scripts/benchmark-workbase.mjs
```

The benchmark creates temporary baseline and Workbase-initialized Git projects, then compares setup steps, Trellis+codedb alignment pass rate, diagnostic coverage, reusable context files, handoff files, and automated repair actions. JSON and Markdown reports are written under `benchmark-results/`, which is ignored by git.

Cross-platform install:

```bash
git clone https://gitee.com/KFCheems/ai-workbase.git
cd ai-workbase
node install.mjs
```

codedb automation:

- `node install.mjs` prepares codedb proactively. If `node scripts/init-project.mjs <repo-root>` cannot find a codedb binary, it also tries to run `scripts/install-codedb.mjs` automatically before writing project MCP config.
- If `CODEDB_MCP_BIN` points to a valid binary, the installer reuses it.
- If a Codex skill binary exists locally, the installer copies it into the workbase cache.
- Otherwise it clones `https://github.com/killop/codedb-mcp.git` and builds with `cargo build --release`.
- If Cargo is missing, install Rust or set `CODEDB_MCP_BIN`, then rerun `node scripts/install-codedb.mjs`.