opencli AGENTS.md

AGENTS.md

This file provides guidance to Codex when working with code in this repository. It must be kept in sync with CLAUDE.md — see docs/engineering-practices.md.

Project Overview

OpenCLI — an open-source AI agent CLI that supports Google Gemini and Anthropic Claude models, modeled after Claude Code. The implementation is a working prototype in TypeScript/Node.js (ESM, Node 20+).

Getting Started with a Task

New to this project? Start here: Task Workflow — it walks you through the typical task lifecycle, from reading the issue to committing your work. It references this document and docs/engineering-practices.md for the conventions you need to know.

Commands

npm run dev               # Run interactive REPL (auto-loads .env)
npm run dev run "<prompt>"  # One-shot prompt
npm run build             # Bundle with tsup → dist/
npm run typecheck         # tsc --noEmit
npm run lint              # ESLint
npm run lint:fix          # ESLint with auto-fix
npm run format            # Prettier --write src/**/*.ts
npm run format:check      # Prettier check (no write)
npm test                  # Vitest
npm run test:single       # Vitest verbose (single run)

API keys are loaded from .env (GEMINI_API_KEY for Gemini models, ANTHROPIC_API_KEY for Claude models). Default model: gemini-3.1-flash-lite-preview.

Source Structure

src/
  cli/            # Thin adapter — reads config/env, wires dependencies, runs the REPL
    index.ts        # Entry point — commander CLI (chat / run / sessions / config commands)
    repl.ts         # Interactive REPL, /slash command interception, skill loading, session logging
    renderer.ts     # MarkdownStreamRenderer (paragraph-level streaming), tool call display
    input.ts        # Raw-mode readline, /slash popup with arrow-key navigation
    confirm.ts      # HITL confirmation dialog (y/n/always); reads and writes settings
    keys.ts         # API key resolution — env var → config file lookup
    mcp-cmd.ts      # /mcp slash command handler (list, add, remove, test)
    mentions.ts     # @-mention expansion — resolves @file references before the agent sees them
    plan.ts         # /plan slash command handler — plan pass → approval → react execution
    runner.ts       # runAgentTurn() helper extracted from repl.ts
  core/           # Pure library — no process.env reads, no CLI/state imports
    agent.ts        # Agentic loop: stream → collect function calls → execute → feed back
    executor.ts     # Parallel tool execution, skill activation dispatch, HITL confirmation gate,
                    #   provenance-tracking confirmation bump (#309): results from web_fetch/mcp__*/
                    #   out-of-project reads are tagged untrusted; while any is consumed this turn,
                    #   outbound/mutating tools (bash/write/edit/multi_edit/web_fetch/mcp__*) are forced
                    #   through the gate (same-batch reads arm it pre-dispatch)
    context.ts      # Conversation history, skill content injection, context pruning
    prompt.ts       # DEFAULT_SYSTEM_INSTRUCTION template + loadSystemInstruction() (OPENCLI_SYSTEM_MD)
    compact.ts      # compactContext() — LLM-based context compaction for /compact command
    observability.ts # ObservabilityEvent types; token + turn metrics emitted by the agent loop
  providers/      # LLM clients — no CLI/state imports
    types.ts        # Shared types: Message, StreamEvent, ToolDefinition, ToolResult, thoughtSignature
    client.ts       # LLMClient interface — the provider plug point
    registry.ts     # PRESETS — single source of truth for provider wire format, base URL, key env
                    #   vars, context windows, capabilities. Adding a provider is a data change.
    gemini.ts       # GeminiClient implements LLMClient; Gemini-specific schema conversion internal
    anthropic.ts    # AnthropicClient implements LLMClient; translates role/tool formats internally
    openai.ts       # OpenAIClient implements LLMClient; also serves every OpenAI-compatible OSS
                    #   provider and local Ollama
    salvage.ts      # Recovers tool calls OSS models emit as text instead of structured tool_calls
    ollama-discovery.ts # Best-effort /api/tags query — local context window + tool capability
    factory.ts      # createClient(model, apiKey) — picks provider via the registry
    schema.ts       # Generic toolToDefinition() + activateSkillDefinition (plain JSONSchema, no provider deps)
    retry.ts        # withRetry() — shared exponential-backoff retry wrapper for provider streams
    errors.ts       # toFriendlyError() — normalises provider errors to human-readable messages
  tools/
    base.ts         # Tool interface + JSONSchema type
    registry.ts     # ToolRegistry: register, execute, list
    file/           # read, write, edit, multi_edit, glob, grep, ls; paths.ts (symlink-aware containment + credential-path checks)
    exec/           # bash (with requiresConfirmation for non-safe commands); sandbox/ (bwrap, sandbox-exec, passthrough)
    web/            # web_fetch tool
    task/           # todo_write and todo_read tools
    think.ts        # think tool — private scratchpad; skipped for native-thinking models
    index.ts        # createDefaultRegistry(model?, runner?) factory — omits think for native-thinking models
  skills/
    registry.ts     # Discover SKILL.md files across 4 scoped directories
    loader.ts       # Parse SKILL.md frontmatter, !{cmd} preprocessing, $ARGUMENTS substitution
    builtin/        # review, commit, explain, debug, test, gh-issue, gh-pr, branch, run-tests, typecheck, lint, new-skill, changelog
  mcp/            # MCP integration — bridges external tool servers into ToolRegistry
    types.ts        # McpStdioServer, McpHttpServer, McpServerConfig, McpConfig, McpToolInfo
    config.ts       # loadMcpConfig(agentDir) — reads ~/.opencli/mcp.json; expands ${VAR} refs
    client.ts       # McpClient — connects via stdio or HTTP, enforces per-server callTimeout
    adapter.ts      # mcpToolToTool() — wraps one MCP tool as a Tool (name: mcp__server__tool)
    manager.ts      # McpManager — connects all servers in parallel, registers adapters
    index.ts        # Re-exports all public types and classes
  state/
    config.ts       # ~/.opencli/config.json load/save; exports AGENT_DIR, Config (incl. anthropicApiKey)
    session.ts      # JSONL session logs at ~/.opencli/projects/<cwd>/; create, list, resume
    settings.ts     # .opencli/settings.json load/save; holds project-level Permissions (HITL allow/ask/deny list)
    snapshot.ts     # SnapshotManager — git stash create/restore for per-session working-tree snapshots