@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>`
├── hooks/hooks.json                # optional automatic session-summary hooks
├── scripts/auto-summary.cjs        # hook runner for automatic Tree Hole summaries
└── 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.

Automatic summaries are installed with the plugin but are disabled by default to avoid surprise persistence. Enable them explicitly after credentials are configured:

npx @agentlas/claude-code config --auto-summary true

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_..."

# Preferences
npx @agentlas/claude-code config --confirm-before-save true
npx @agentlas/claude-code config --auto-summary true
npx @agentlas/claude-code config --auto-summary-triggers precompact,clear,session-end

# 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.

Automatic summaries

Claude Code loads hooks/hooks.json from installed plugins by convention. This plugin registers:

• PreCompact — primary path. Runs before manual /compact and automatic context compaction.
• SessionEnd with reason: "clear" — handles /clear.
• SessionEnd for all other reasons — final fallback.

Enable or inspect the feature:

npx @agentlas/claude-code config --auto-summary true
npx @agentlas/claude-code config --auto-summary-triggers precompact,clear,session-end
npx @agentlas/claude-code config --show
npx @agentlas/claude-code config --auto-summary false

The hook reads Claude Code's transcript_path, asks claude --print to produce a knowledge-first extraction, then saves it through the Agentlas Tree Hole API with source: "knowledge_extraction". PreCompact runs synchronously so the summary is captured before compaction. SessionEnd runs as a detached background task so /clear, exit, and resume flows are not blocked or cancelled by a long model call. The hook stores a per-session transcript cursor in ~/.agentlas/claude-code-auto-summary-state.json, so /clear and final SessionEnd only summarize content that was added after any prior PreCompact summary. Hook failures are reported on stderr and do not block compaction or session exit.

The transcript is treated as untrusted content and is redacted before summarization, but redaction is best-effort. Do not rely on this feature to sanitize secrets intentionally pasted into a session transcript.

Configuration lives in:

~/.agentlas/config.json

Default config after enabling:

{
  "apiBaseUrl": "https://your-agentlas-domain.com",
  "apiToken": "sk_live_xxxxxxxx",
  "claudeCode": {
    "autoSummary": {
      "enabled": true,
      "minChars": 2000,
      "triggers": ["precompact", "clear", "session_end"]
    }
  }
}

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.