Agent engine

XibeCode’s core (xibecode-core) runs an autonomous coding agent: model calls → tool use → file/shell changes → verify → continue until the task is done or you stop it.

Surfaces

Agent loop

1. Build context (project files, curated memory, skills, session history).
2. Call the LLM with tools (read/write/edit, shell, search, MCP, etc.).
3. Execute tool calls safely under permission rules.
4. Feed results back; repeat until:
   • the model finishes with a final answer, or
   • you abort (Ctrl+C, chat cancel, daemon /stop), or
   • a finite iteration cap is hit.

On tool failure, the engine injects a recovery message (retry with new params, alternative tool, or finish with a failure summary) so runs do not spin silently.

Max iterations (unlimited by default)

# Unlimited (default)
xibecode run "refactor auth module"

# Cap at 100 turns
xibecode run "…" -d 100

# Profile default
xibecode config  # or setup agent → Max agent iterations = 0

Economy cost mode still applies a separate lower cap (economyMaxIterations) so cheap runs stay bounded.

Anti-runaway: repeated identical tool calls are blocked by the loop detector; you can always interrupt.

Auto-compact

When the conversation nears the model’s context budget, XibeCode auto-compacts so long tasks can continue.

When it triggers

• Preflight and post-turn checks each agent iteration.
• Roughly ~75% of context for typical windows (≤512k), ~50% for huge windows.
• Always leaves headroom: never later than window − autoCompactThreshold (default ~13k tokens free for the next reply).

What happens

1. Microcompact — strip or shrink old tool results.
2. Full handoff — structured summary + grounded facts ledger + token-budget tail (not a fixed message count).
3. Prior compaction summaries are folded in; the model is told not to re-answer resolved work.

User-visible status

• Compacting context — summarizing earlier conversation…
• Context compacted · … tokens

(Telegram/daemon shows the same as progress messages.)

Disable / tune

{
  "autoCompactEnabled": false,
  "autoCompactThreshold": 13000
}

XIBECODE_AUTO_COMPACT=0   # disable

Lifecycle hooks: PreCompact / PostCompact (see Hooks).

Modes

Modes control tool categories and behavior (agent, plan, review, debugger, …). See Modes. Plan and review modes still allow shell where needed for verification.

Tools

File ops, shell, search, web fetch, memory (curated_memory, project memory), skills (list_skills / view_skill), swarm, MCP tools, screenshots, and more. See Tools.

Browser note: Playwright is not bundled. Prefer agent-browser (optional install) or host Chromium for screenshots; other browser audit tools may return guidance stubs.

Learning & memory

After turns, optional learning loop features:

• Curated MEMORY.md / USER.md (frozen at session start; disk updates immediate for next session)
• Post-turn review (optional cheap model)
• Write-approval for sensitive memory/skill writes
• Session search across past work
• Skill learner for reusable procedures

See Memory.

Providers & models

Any catalog entry from Providers. Live /models, models.dev registry, and curated fallbacks. Failover pools improve reliability under rate limits.

Cloud execution

Optional E2B sandbox runtime: shell in the cloud while files stay on host (host_only) or full workspace sync (sandbox_full). See Cloud / E2B.

File history / checkpoints

On-disk checkpoints under ~/.xibecode/file-history/ with message-linked snapshots. Disable with XIBECODE_DISABLE_FILE_CHECKPOINTING=1.

Best practices

1. Run xibecode setup once, then xibecode chat for interactive work.
2. Prefer unlimited iterations for large refactors; use -d N only when you want a hard budget.
3. Use economy mode for cheap drafts; normal mode for production changes.
4. For always-on coding from phone/Telegram, install the daemon and use /stop if a run goes wrong; /cmd for quick shell without the agent.
5. Let auto-compact run on long chats; only disable if you need the full raw history in context.