@agentlas/codex

Codex plugin for Agentlas. Adds Tree Hole note and knowledge-extraction skills backed by the Agentlas MCP server (@agentlas/mcp).

Codex plugins use skills + MCP rather than slash commands, so users invoke this through natural language ("把这段话发到树洞 …", "总结本次 session 发到树洞").

Layout

.
├── .codex-plugin/plugin.json
├── bin/codex.js                    # install + config CLI
├── .mcp.json                       # registers the agentlas MCP server via `npx -y @agentlas/mcp@<pinned>`
├── scripts/auto-summary.cjs        # automatic Tree Hole summary runner
├── shell/                          # shell wrappers used for session-end summaries
└── skills/
    ├── agentlas-treehole/SKILL.md
    └── agentlas-knowledge-extraction/SKILL.md

Install

One-shot install + configure (recommended)

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

Restart Codex. Done.

Install separately

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

Restart Codex.

Already configured another Agentlas host?

Credentials live in ~/.agentlas/config.json and are shared across every Agentlas host plugin. If you ran config already (e.g. via @agentlas/claude-code), the codex installer detects this and skips the credential prompt:

npx @agentlas/codex install
# →  Installed Codex Agentlas plugin to ~/.codex/plugins/agentlas-plugins/plugins/agentlas
#    Using existing Agentlas credentials (~/.agentlas/config.json).
#    Next step: Restart Codex.

Reinstall / upgrade

npx @agentlas/codex install --force

~/.agentlas/config.json is not touched, so reinstalls and upgrades never lose your token.

Uninstall

npx @agentlas/codex uninstall

~/.agentlas/config.json is intentionally kept (other host plugins may still need it). Run npx @agentlas/codex config --unset to remove credentials too.

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/codex config --base-url "https://..." --api-key "sk_live_..."

# Preferences
npx @agentlas/codex config --confirm-before-save true
npx @agentlas/codex config --auto-summary true --yes

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

# Remove
npx @agentlas/codex config --unset

config --show reports whether values come from env vars or the file, plus the saved Tree Hole and Codex auto-summary preferences. Codex auto-summary configuration is stored under codex.autoSummary.

Auto Summary

# Enable automatic Codex summaries
npx @agentlas/codex config --auto-summary true --yes

# Disable automatic Codex summaries
npx @agentlas/codex config --auto-summary false --yes

Enabling auto-summary installs a shell wrapper into your zsh/bash/fish rc file, copies a stable runtime to ~/.agentlas/codex-auto-summary-runtime, writes the runner at ~/.agentlas/codex-wrapper-runner.js, and merges a Codex PreCompact hook into ~/.codex/hooks.json. Session-end summaries are captured by the shell wrapper; PreCompact summaries are captured by the Codex hook. The runner fails closed when it cannot identify a single matching rollout. PreCompact matching relies on the rollout cwd being unique among active sessions.

Env-var override (CI / Docker / temporary)

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

The MCP server reads env first, file second.

Custom config directory

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

What .mcp.json does

The installed .mcp.json only registers npx -y @agentlas/mcp@<exact-version> — pinned to a specific version because the MCP server is in the 0.x range and every minor release may be breaking. There is no env-var interpolation in it anymore — the MCP server reads ~/.agentlas/config.json (or env vars) on its own. This means:

• Plugin reinstalls (install --force) cannot wipe credentials.
• Switching hosts (codex ↔ claude-code) inherits the same credentials with zero reconfiguration.
• The token is never written into Codex's host-level config.

Where the install actually goes

The installer copies the plugin into a local marketplace at ~/.codex/plugins/agentlas-plugins/plugins/agentlas, writes a real copy into Codex's plugin cache at ~/.codex/plugins/cache/agentlas-plugins/agentlas/<version>, and enables agentlas@agentlas-plugins in ~/.codex/config.toml.

Usage

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

Knowledge extraction examples:

总结本次 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-codex 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.
• Plugin doesn't appear after install — restart Codex and confirm ~/.codex/config.toml contains [plugins."agentlas@agentlas-plugins"].
• Credentials not picked up after config — restart Codex so the MCP server is re-spawned.