@agentlas/claude-code

Claude Code plugin for Agentlas. Adds Tree Hole slash-command and model-invocable skills backed by the Agentlas MCP server (@agentlas/mcp).

Layout

.
├── .claude-plugin/
│   ├── marketplace.json            # self-marketplace pointing at this package directory
│   └── plugin.json
├── bin/claude-code.js              # install + config CLI
├── .mcp.json                       # registers the agentlas MCP server via `npx -y @agentlas/mcp@<pinned>`
└── skills/
    ├── treehole/SKILL.md           # /agentlas:treehole <text>  +  natural-language ("发到树洞")
    └── extract-knowledge/SKILL.md  # /agentlas:extract-knowledge + natural-language knowledge extraction

Install

One-shot install + configure (recommended)

Configure credentials inline so you never need a second command:

npx @agentlas/claude-code install \
  --base-url "https://your-agentlas-domain.com" \
  --api-key  "sk_live_xxxxxxxx"

Restart Claude Code. Done.

Install separately

If you want to install now and configure later:

npx @agentlas/claude-code install
npx @agentlas/claude-code config \
  --base-url "https://your-agentlas-domain.com" \
  --api-key  "sk_live_xxxxxxxx"

Restart Claude Code.

Already configured another Agentlas host?

If you previously ran config for any Agentlas host plugin (codex, openclaw, etc.), credentials live in ~/.agentlas/config.json and are shared. The installer detects this and skips the credential prompt:

npx @agentlas/claude-code install
# →  Installed Claude Code Agentlas plugin (agentlas@agentlas-plugins) at user scope.
#    Using existing Agentlas credentials (~/.agentlas/config.json).
#    Next step: Restart Claude Code.

Where the marketplace lives on disk

The installer copies the marketplace contents (.claude-plugin/, .mcp.json, skills/, README.md) into a stable location at ~/.claude/agentlas/marketplace/ and registers that path with Claude Code. This is intentional: npx -y @agentlas/claude-code runs the bin out of npm's _npx cache, which npm garbage-collects, so registering the bin's source directory directly would break Claude Code as soon as the cache was cleaned. The stable copy survives.

CLAUDE_CONFIG_DIR (default ~/.claude) overrides the parent location.

Reinstall / upgrade

npx @agentlas/claude-code install --force

Credentials at ~/.agentlas/config.json are not touched, so reinstalls and upgrades never lose them. The staged marketplace at ~/.claude/agentlas/marketplace/ is rebuilt from the new package contents.

Scopes

By default the installer uses Claude Code's user plugin scope:

npx @agentlas/claude-code install --scope project
npx @agentlas/claude-code install --scope local

Uninstall

npx @agentlas/claude-code uninstall

~/.agentlas/config.json is intentionally kept (other host plugins may still need it). Run npx @agentlas/claude-code config --unset to remove credentials too. The staged marketplace at ~/.claude/agentlas/marketplace/ is also kept (other Claude Code plugin scopes may still reference it); delete the directory manually if you want a clean slate.

Configure

Credentials are stored in one user-level file shared by every Agentlas host plugin:

~/.agentlas/config.json    # chmod 0600, dir chmod 0700
{
  "apiBaseUrl": "https://your-agentlas-domain.com",
  "apiToken": "sk_live_xxxxxxxx"
}

CLI

# Set
npx @agentlas/claude-code config --base-url "https://..." --api-key "sk_live_..."

# Inspect (token is masked)
npx @agentlas/claude-code config --show

# Remove
npx @agentlas/claude-code config --unset

config --show reports whether values come from env vars or the file.

Env-var override (CI / Docker / temporary)

If AGENTLAS_API_BASE_URL and AGENTLAS_API_TOKEN are set in the Claude Code process environment, they take priority over ~/.agentlas/config.json. The MCP server reads the env first and falls back to the file:

AGENTLAS_API_BASE_URL=https://example.com \
AGENTLAS_API_TOKEN=sk_live_xxx \
claude

Custom config directory

export AGENTLAS_CONFIG_DIR="$HOME/.agentlas-staging"
npx @agentlas/claude-code config --base-url ... --api-key ...

The CLI and the MCP server both honor AGENTLAS_CONFIG_DIR.

What .mcp.json does

.mcp.json runs npx -y @agentlas/mcp@<exact-version> at startup — pinned to a specific version because the MCP server is in the 0.x range and every minor release may be breaking. The server reads ~/.agentlas/config.json (or env vars) directly — there is no host-side env interpolation, so plugin reinstalls and Claude Code settings changes never affect saved credentials.

Alternative installation paths

GitHub marketplace (team members with repo access)

/plugin marketplace add agentlas/agentlas-plugins
/plugin install agentlas

Manual npm marketplace

npm i -g @agentlas/claude-code
echo "$(npm root -g)/@agentlas/claude-code"

Then:

claude plugin marketplace add <that-path>
claude plugin install agentlas@agentlas-plugins

Standalone MCP only

claude mcp add --transport stdio agentlas -- npx -y @agentlas/mcp@<pinned>
# (assumes you have run `agentlas-claude-code config` or set env vars)

Usage

/agentlas:treehole 今天有点累，但还是把最重要的事情推进了一点

Or in normal chat:

帮我把这段话发到树洞：今天有点累，但还是把最重要的事情推进了一点

To extract reusable knowledge from the current session and save it:

/agentlas:extract-knowledge

总结本次 session 发到树洞
把本轮上下文存成 memory，保留关键决策和待办
提取这次对话里可复用的知识和踩坑经验，保存到树洞

The plugin sends a POST /api/tree-hole-posts request to Agentlas with { "visibility": "private", "body": "..." }. The post author is determined by the saved API key.

Troubleshooting

• 还没有配置 Agentlas 服务地址 — apiBaseUrl is missing. Run agentlas-claude-code config --base-url ... --api-key ....
• 还没有配置 Agentlas API Token — apiToken is missing. Same fix.
• Agentlas API Token 无效或已失效 — create a fresh API key in Agentlas Settings, then rerun config.
• 树洞保存失败，请稍后再试 — the Agentlas server is unreachable or /api/tree-hole-posts is unhealthy.
• MCP server doesn't start — check that npx -y @agentlas/mcp@<pinned> succeeds in your shell; npm registry access is required at first run.
• This plugin uses a source type your Claude Code version does not support — remove and re-add the marketplace after upgrading to the latest @agentlas/claude-code.
• Marketplace "agentlas/claude-code" not found — Claude Code's /plugin install does not accept filesystem paths. Use /plugin marketplace add <path> first.
• Credentials not picked up after config — restart Claude Code so the MCP server is re-spawned.