@lwmxiaobei/xbcode
Advanced tools
xbcode is a TypeScript-based CLI coding agent built with OpenAI SDK and Ink. It runs in the terminal, streams model output, executes local tools, supports persistent tasks, skills, MCP integration, and lightweight multi-agent teamwork.
The project is positioned as a compact, hackable alternative to heavier coding agents: small enough to read end-to-end, but already opinionated enough to be useful in day-to-day coding workflows.
xbcode is an early open source product focused on being practical, readable, and easy to extend. The current priority is reliability, usability, and contributor experience.
Related project docs:
.tasks/npm install -g @lwmxiaobei/xbcode
Or run locally in this repo:
npm install
npm run dev
On install, xbcode creates a default config file at:
~/.xbcode/settings.json
Minimal example:
{
"providers": {
"openai": {
"models": [
{ "id": "gpt-4.1", "name": "GPT-4.1" },
{ "id": "gpt-4.1-mini", "name": "GPT-4.1 Mini" },
{ "id": "o3-mini", "name": "o3 Mini" }
],
"apiKey": "YOUR_OPENAI_API_KEY",
"baseURL": "https://api.openai.com/v1",
"apiMode": "responses"
}
},
"defaultProvider": "volcengine",
"defaultModel": "doubao-seed-2.0-code",
"showThinking": false,
"mcp": {
"servers": []
}
}
xbcode
Local development:
npm run dev
Build and run compiled output:
npm run build
npm start
After launch, enter a request such as:
Read the project structure and explain how the agent loop works.
If MODEL_ID is not preset in the environment, the CLI will guide you through interactive provider/model selection from ~/.xbcode/settings.json.
The generated default config now prefers Volcengine Ark and defaults to doubao-seed-2.0-code.
The built-in web_search tool uses Brave Search API. Configure the API key in the project .env file or in the current shell:
BRAVE_SEARCH_API_KEY=your Brave Search API key
When the model needs current information, it can call web_search to discover candidate results and then use web_fetch to read selected pages.
At a high level, xbcode runs a standard think-act loop:
AGENTS.md.The current implementation supports two backend styles:
responses
Uses OpenAI Responses API and chains turns via previous_response_idchat-completions
Uses local chat history and supports compatible endpoints such as DeepSeek-style APIsPackage scripts:
npm run dev
npm run build
npm run test
npm start
Published binary:
xbcode
Built-in slash commands currently include:
/help/status/goal [objective]/goal pause/goal resume/goal budget <tokens>/goal clear/login/logout/mcp/mcp refresh/team/inbox/provider/model/compact/new/exitSkill prompt-commands are also exposed as slash commands when available from loaded skills.
/goal <objective> creates a session-persistent goal and keeps starting continuation turns until the model marks it complete or blocked, the user pauses it, an error pauses it, or its token budget is exhausted. Goal state and usage are saved with the session and restored by /resume.
Providers are configured in ~/.xbcode/settings.json:
{
"providers": {
"openai": {
"models": [
"gpt-4.1",
{ "id": "gpt-4.1-mini", "name": "GPT-4.1 Mini", "description": "Fast general model" }
],
"apiKey": "YOUR_KEY",
"baseURL": "https://api.openai.com/v1",
"apiMode": "responses",
"auth": {
"type": "oauth"
}
},
"aliyun": {
"models": ["qwen-plus", "qwen-turbo", "qwen-max"],
"apiKey": "sk-xxx",
"baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1"
},
"volcengine": {
"models": [
{ "id": "doubao-seed-2.0-code", "name": "Doubao Seed 2.0 Code" },
{ "id": "doubao-seed-2.0-pro", "name": "Doubao Seed 2.0 Pro" },
{ "id": "doubao-seed-2.0-lite", "name": "Doubao Seed 2.0 Lite" },
{ "id": "doubao-seed-code", "name": "Doubao Seed Code" },
{ "id": "minimax-m2.7", "name": "MiniMax M2.7" },
{ "id": "minimax-m3", "name": "MiniMax M3" },
{ "id": "glm-5.1", "name": "GLM 5.1" },
{ "id": "glm-5.2", "name": "GLM 5.2" },
{ "id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash" },
{ "id": "deepseek-v4-pro", "name": "DeepSeek V4 Pro" },
{ "id": "kimi-k2.6", "name": "Kimi K2.6" }
],
"apiKey": "YOUR_ARK_API_KEY",
"baseURL": "https://ark.cn-beijing.volces.com/api/coding/v3",
"apiMode": "chat-completions"
}
},
"defaultProvider": "openai",
"showThinking": false
}
Key fields:
providers
Named provider profilesmodels
A list of model IDs or richer model descriptorsdefaultProvider
Used when no provider is explicitly selectedshowThinking
Enables display of model reasoning deltas when supportedapiMode
Either responses or chat-completionsauth
Optional provider auth mode. Today only { "type": "oauth" } is supported, and only for OpenAI.API mode can be explicit, or derived automatically. For example, DeepSeek-, DashScope-, and Volcengine Ark-compatible base URLs default to chat-completions.
For Volcengine Ark, configure the provider with your Ark API key, use https://ark.cn-beijing.volces.com/api/coding/v3 as baseURL, and put the model IDs you can access into models. Example IDs include doubao-seed-2.0-code, doubao-seed-2.0-pro, doubao-seed-2.0-lite, doubao-seed-code, minimax-m2.7, minimax-m3, glm-5.1, deepseek-v4-flash, deepseek-v4-pro, and kimi-k2.6.
When OpenAI OAuth is enabled:
~/.xbcode/settings.json~/.xbcode/credentials.jsonaccess_tokenxbcode falls back to the provider apiKey when one is configuredOAuth commands:
/login openai
/logout openai
/login without an argument uses the current provider. In this first version, the CLI prints the OpenAI authorization URL in the terminal and waits for the localhost callback to complete.
xbcode uses the current working directory as its default base, but file tools are not sandboxed:
.. segments, and absolute pathsprocess.cwd()cwd = process.cwd()<workdir>/skills<workdir>/.team<workdir>/.tasksIf the current project contains an AGENTS.md, its contents are injected into the system prompt and influence agent behavior.
The lead agent has access to:
bashread_filewrite_fileedit_filetask_createtask_updatetask_listtask_getlist_mcp_resourcesread_mcp_resourcemcp_callload_skilltaskmessage_sendteammate_spawnteammate_listteammate_shutdownlead_inboxTeammates get a reduced tool surface:
message_sendThis is a deliberate constraint to prevent uncontrolled recursive delegation.
The task system is persistent and file-backed. Each task is stored as a JSON file under:
.tasks/task_<id>.json
Task fields include:
idsubjectdescriptionstatusblockedByblocksSupported statuses:
pendingin_progresscompletedWhen a task is marked completed, dependent tasks are automatically unblocked.
Skills provide reusable instructions and domain-specific guidance. They are loaded from three locations:
~/.xbcode/skills~/.claude/skills<workdir>/skillsLoading order matters:
~/.xbcode/skills is loaded first~/.claude/skills is loaded next for compatibilitynameEach skill is defined by a SKILL.md file with frontmatter. The loader exposes:
load_skillTwo example local skills ship in this repo:
skills/pdf/SKILL.mdskills/code-review/SKILL.mdMCP server configuration lives in:
~/.xbcode/settings.json
Supported transports:
stdiostreamable-httpExample:
{
"mcp": {
"servers": [
{
"name": "filesystem",
"enabled": true,
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
"cwd": "/path/to/project",
"timeoutMs": 30000
}
]
}
}
Current MCP behavior:
list_mcp_resourcesread_mcp_resourcemcp_callFor deeper details, see:
xbcode supports persistent teammates instead of only one-shot sub-agents.
Conceptually:
lead is the main CLI-facing agentTeam state is stored under:
.team/
config.json
inbox/
lead.jsonl
<teammate>.jsonl
Useful tools:
teammate_spawnteammate_listteammate_shutdownmessage_sendlead_inboxThis model supports asynchronous collaboration while keeping contexts isolated per agent.
For the design background, see docs/agent-teams.md.
code-agent/
src/
index.tsx CLI UI and input loop
agent.ts core agent loop
tools.ts tool definitions and handlers
config.ts settings loading and provider resolution
prompt.ts system prompt construction
compact.ts context compaction logic
task-manager.ts persistent task storage
message-bus.ts inbox-based messaging
teammate-manager.ts persistent teammate lifecycle
mcp/ MCP runtime, manager, client, types
skills/ skill parsing and rendering
test/ node:test test suite
docs/ design and implementation notes
skills/ example local skills
scripts/postinstall.mjs default config bootstrap
src/index.tsxResponsible for:
src/agent.tsResponsible for:
src/tools.tsResponsible for:
src/config.tsResponsible for:
~/.xbcode/settings.jsonsrc/prompt.tsResponsible for building the static system prompt from:
AGENTS.mdsrc/compact.tsImplements two levels of history control:
microCompact
Shrinks old tool outputs in local chat historyautoCompact
Summarizes history and replaces it with a compressed summaryResponses mode uses a different strategy: periodic reset of the previous_response_id chain.
Best fit for:
Behavior:
previous_response_idBest fit for:
Behavior:
There are two delegation models:
task
Creates a one-shot isolated sub-agent with a clean context and a bounded maximum round countUse task for isolated execution. Use teammates for ongoing coordination.
Run the test suite with:
npm test
Current tests cover areas such as:
The test runner uses native node:test with tsx.
The package is published as:
@lwmxiaobei/xbcode
Important package details:
xbcodedist/prepublishOnly runs build plus testsThe current implementation intentionally enforces several simple constraints:
This is not a hardened sandbox. It is a pragmatic local-agent safety layer.
The codebase favors:
That makes it easier to understand, modify, and compare against larger agent implementations.
Notable limitations in the current implementation:
Additional project notes live under docs/:
Install dependencies:
npm install
Run in development:
npm run dev
Run tests:
npm test
Build:
npm run build
No license file is included in this repository snapshot. Add one before public redistribution if needed.
FAQs
Xbcode CLI agent
The npm package @lwmxiaobei/xbcode receives a total of 16 weekly downloads. As such, @lwmxiaobei/xbcode popularity was classified as not popular.
We found that @lwmxiaobei/xbcode demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.
Research
/Security News
Two Joyfill npm beta releases contain an import-time implant that uses blockchain transactions to retrieve a remote-access trojan.
Security News
Socket releases free Certified Patches for high-severity Nuxt vulnerabilities, including server-side remote code execution through server island props.