Personal Agentic Workspace¶

A tool-agnostic AI collaboration workspace. Organized by function — find what you need by what you want to do.

Getting started¶

Prerequisites: Python 3.11+, uv, git. Optional, only for the capabilities that need them: Calibre + Ollama (library/), Ollama (research/), Node.js/npm (AnyType MCP via npx), the AnyType desktop app (PKM).

1. Clone and enable the drift-check hook:

   git clone git@gitlab.com:maker-nathan/tool-chest.git && cd tool-chest
   make hooks
   

2. Configure — review tool-chest.toml and adjust paths (e.g. calibre_library) for your machine, and set any secrets in your shell profile (never in the file itself). Details: Configuration.
3. Generate client configs and verify the clone is clean:

   make mcp-config   # writes .mcp.json / .cursor/mcp.json from tool-chest.toml
   make check        # fails if anything has drifted (mcp-check + rules-check + docs-config-check)
   

4. Open the repo in Cursor or Claude Code. Skills and rules load automatically from .cursor/skills/ / .cursor/rules/ (symlinked from shared/) — no extra install step.
5. Set up whichever standalone tools you want, each self-contained via uv:
6. cd library && uv sync — e-book RAG (needs Calibre + Ollama)
7. cd research && uv sync — Anthropic research RAG (needs Ollama)
8. cd local-agent && uv run local-agent --help — local org-navigator (no external deps)
9. Browse these docs as a site (optional), via Zensical (Material for MkDocs' successor — classic mkdocs' maintainer situation has stalled, and mkdocs-material never shipped support for the interim 2.0 rewrite):

   pip install -r requirements.txt
   make docs-serve   # exports tracked files to docs-build/, then serves at http://127.0.0.1:8000
   

   Config: zensical.toml, fully generated — don't hand-edit it. Nav is derived from every tracked markdown file (make docs-config-sync / make docs-config-check, part of make check) — add a new doc and it appears on next sync. make docs-build writes the static site to site/. Note: Zensical is alpha software as of this writing.

Capability map¶

Layout¶

.
├── shared/              Canonical tool-agnostic resources (skills, rules, agents)
├── knowledge/           Information stores
│   ├── agent-wiki/      Machine-readable context for agents
│   └── anytype-integration/  AnyType PKM config and bridging
├── workflow/            How work gets done
│   ├── task-loop.md     Default bounded task loop
│   ├── delegation/      Agent delegation templates and audit log
│   └── handoff/         Project handoff protocol
├── governance/          Policies, audit, security sandbox, docs/publish
├── instrumentation/     Metrics and friction logging
├── library/             calibre-librarian — local RAG over a Calibre e-book library (MCP)
├── research/            anthropic-research — local RAG archive of Anthropic's published research (MCP)
├── local-agent/         Local-first org-navigator: capture/query working relationships (no cloud)
├── integrations/        Bridges between library/research and PKM (e.g. agent-wiki logging)
├── assets/              Static assets (icon, images)
├── scripts/             Config generation and drift-check scripts (see Configuration below)
└── .cursor/             Cursor-specific config (references shared/ where possible)

Operating principles¶

1. Single source of truth. Canonical assets live in shared/. Tool configs reference it.
2. Capture everything, triage later. Use pkm-capture or AnyType inbox; don't let things fall through.
3. Delegate with a paper trail. Every agent task gets a delegation template and an audit log entry.
4. Privacy by default. Sensitive data stays local; cloud only with explicit opt-in.
5. One capability at a time. Add skills when a real need surfaces, not speculatively.

Configuration¶

All user-facing preferences live in tool-chest.toml at the repo root — one file to edit.

[local_agent]
model = "mistral:7b"         # local Ollama model for chat capture

[local_agent.ollama]
base_url = "http://localhost:11434"

[anytype]
api_base_url = "http://127.0.0.1:31009"

Scripts and launchers read from this file automatically (via scripts/config_loader.py). Shell environment variables override config values, so you can do LOCAL_AGENT_MODEL=foo ./chat for one-off overrides without editing the file.

Secrets never go in tool-chest.toml. Set them in your shell profile:

# Anytype MCP authentication (SPB-09: never commit tokens)
export ANYTYPE_OPENAPI_MCP_HEADERS='{"Authorization":"Bearer <key>","Anytype-Version":"2025-11-08"}'

To make the Anytype MCP URL available when Cursor starts, source the loader in your shell profile:

eval "$(python3 /path/to/tool-chest/scripts/config_loader.py --export)"

MCP servers¶

Claude Code and Cursor read different files and use incompatible placeholder syntax (${NAME} vs ${env:NAME}, ${CLAUDE_PROJECT_DIR} vs ${workspaceFolder}), so they cannot share one config. Instead, both are generated from the [mcp.*] section of tool-chest.toml:

make mcp-config        # regenerate .mcp.json and .cursor/mcp.json
make mcp-check         # fail if either has drifted from tool-chest.toml
make mcp-install-user  # install scope="user" servers into ~/.claude.json
                       # and ~/.cursor/mcp.json, so they load in any repo

Add or change a server by editing tool-chest.toml and re-running make mcp-config — never by editing the generated files, which make mcp-check will flag. Restart the client for changes to attach.

A server's scope decides where it lands. scope = "project" servers go in the committed project configs and load only inside tool-chest. scope = "user" servers are installed globally by make mcp-install-user and deliberately left out of the project configs — Claude Code resolves name collisions as local > project > user, so listing a server in both places lets the project entry shadow the user one rather than fall back to it.

Shared rules¶

.cursor/rules/ is composed from shared/rules/ according to rules-manifest.yaml (validated against shared/rules/bootstrap/manifest.schema.json):

make rules-sync    # re-render .cursor/rules/ from the manifest
make rules-check   # fail if .cursor/rules/ has drifted from the manifest

Edit rules in shared/rules/, or change which slices this project inherits in rules-manifest.yaml, then re-run make rules-sync. Never hand-edit .cursor/rules/ — the entries are symlinks, and make rules-check flags a file that has become a copy or that no manifest layer declares.

The manifest's rendered.mode is symlink here rather than copy, since the composed files are byte-identical to their sources: drift is then structurally impossible instead of merely detected. This matches .cursor/skills/, which already symlinks into shared/skills/.

make check runs every drift gate (mcp-check + rules-check), and make hooks installs the pre-commit hook that runs it. Do that once per clone.

Tool setup¶

• Claude Code: Skills at ~/.claude/skills/; definitions documented in shared/skills/
• Cursor: Skills at .cursor/skills/; rules at .cursor/rules/ (both symlinked from shared/)
• AnyType: Local instance with MCP access; config at knowledge/anytype-integration/

Phase roadmap¶

Icon Attribution & Credit: Toolbox by Muhammad Nur Auliady Pamungkas from Noun Project (CC BY 3.0)