axe-cli 1.7.6__py3-none-any.whl → 1.8.0__py3-none-any.whl

axe_cli/README.md

@@ -0,0 +1,304 @@
+# Axe CLI Technical Reference
+
+This document covers the technical details of Axe CLI, including configuration, session management, architecture, and advanced features.
+
+## Sessions and Context Management
+
+axe automatically saves your conversation history, allowing you to continue previous work at any time.
+
+### Session resuming
+
+Each time you start axe, a new session is created. If you want to continue a previous conversation, there are several ways:
+
+**Continue the most recent session:**
+
+Use the `--continue` flag to continue the most recent session in the current working directory:
+
+```bash
+axe --continue
+```
+
+**Switch to a specific session:**
+
+Use the `--session` flag to switch to a session with a specific ID:
+
+```bash
+axe --session abc123
+```
+
+**Switch sessions during runtime:**
+
+Enter `/sessions` (or `/resume`) to view all sessions in the current working directory, and use arrow keys to select the session you want to switch to:
+
+```
+/sessions
+```
+
+The list shows each session's title and last update time, helping you find the conversation you want to continue.
+
+### Startup replay
+
+When you continue an existing session, axe will replay the previous conversation history so you can quickly understand the context. During replay, previous messages and AI responses will be displayed.
+
+### Clear and compact
+
+As the conversation progresses, the context grows longer. axe will automatically compress the context when needed to ensure the conversation can continue.
+
+You can also manually manage the context using slash commands:
+
+**Clear context:**
+
+Enter `/clear` to clear all context in the current session and start a fresh conversation:
+
+```
+/clear
+```
+
+After clearing, the AI will forget all previous conversation content. You usually don't need to use this command; for new tasks, starting a new session is a better choice.
+
+**Compact context:**
+
+Enter `/compact` to have the AI summarize the current conversation and replace the original context with the summary:
+
+```
+/compact
+```
+
+Compacting preserves key information while reducing token consumption. This is useful when the conversation is long but you still want to retain some context.
+
+## Configuration
+
+axe uses configuration files to manage API providers, models, services, and runtime parameters, supporting both TOML and JSON formats.
+
+### Config file location
+
+The default configuration file is located at `~/.axe/config.toml`. On first run, if the configuration file doesn't exist, axe will automatically create a default configuration file.
+
+You can specify a different configuration file (TOML or JSON format) with the `--config-file` flag:
+
+```bash
+axe --config-file /path/to/config.toml
+```
+
+When calling axe programmatically, you can also pass the complete configuration content directly via the `--config` flag:
+
+```bash
+axe --config '{"default_model": "claude-sonnet-4", "providers": {...}, "models": {...}}'
+```
+
+### Config items
+
+The configuration file contains the following top-level configuration items:
+
+| Item | Type | Description |
+|------|------|-------------|
+| default_model | string | Default model name, must be a model defined in models |
+| default_thinking | boolean | Whether to enable thinking mode by default (defaults to false) |
+| providers | table | API provider configuration |
+| models | table | Model configuration |
+| loop_control | table | Agent loop control parameters |
+| services | table | External service configuration (search, fetch) |
+| mcp | table | MCP client configuration |
+
+**Complete configuration example:**
+
+```toml
+default_model = "claude-sonnet-4"
+default_thinking = false
+
+[providers.anthropic]
+type = "anthropic"
+base_url = "https://api.anthropic.com/v1"
+api_key = "sk-ant-xxx"
+
+[models.claude-sonnet-4]
+provider = "anthropic"
+model = "claude-sonnet-4-20250514"
+max_context_size = 200000
+
+[loop_control]
+max_steps_per_turn = 100
+max_retries_per_step = 3
+max_ralph_iterations = 0
+reserved_context_size = 50000
+
+[services.search]
+base_url = "https://api.example.com/search"
+api_key = "sk-xxx"
+
+[services.fetch]
+base_url = "https://api.example.com/fetch"
+api_key = "sk-xxx"
+
+[mcp.client]
+tool_call_timeout_ms = 60000
+```
+
+### providers
+
+`providers` defines API provider connection information. Each provider uses a unique name as key.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| type | string | Yes | Provider type (e.g., anthropic, openai) |
+| base_url | string | Yes | API base URL |
+| api_key | string | Yes | API key |
+| env | table | No | Environment variables to set before creating provider instance |
+| custom_headers | table | No | Custom HTTP headers to attach to requests |
+
+**Example:**
+
+```toml
+[providers.anthropic]
+type = "anthropic"
+base_url = "https://api.anthropic.com/v1"
+api_key = "sk-ant-xxx"
+custom_headers = { "X-Custom-Header" = "value" }
+```
+
+### models
+
+`models` defines available models. Each model uses a unique name as key.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| provider | string | Yes | Provider name to use, must be defined in providers |
+| model | string | Yes | Model identifier (model name used in API) |
+| max_context_size | integer | Yes | Maximum context length (in tokens) |
+| capabilities | array | No | Model capability list |
+
+**Example:**
+
+```toml
+[models.claude-sonnet-4]
+provider = "anthropic"
+model = "claude-sonnet-4-20250514"
+max_context_size = 200000
+capabilities = ["thinking", "image_in", "video_in"]
+```
+
+### loop_control
+
+`loop_control` controls agent execution loop behavior.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| max_steps_per_turn | integer | 100 | Maximum steps per turn |
+| max_retries_per_step | integer | 3 | Maximum retries per step |
+| max_ralph_iterations | integer | 0 | Extra iterations after each user message; 0 disables; -1 is unlimited |
+| reserved_context_size | integer | 50000 | Reserved token count for LLM response generation; auto-compaction triggers when context_tokens + reserved_context_size >= max_context_size |
+
+### services
+
+`services` configures external services used by axe.
+
+**search service:**
+
+Configures web search service. When enabled, the SearchWeb tool becomes available.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| base_url | string | Yes | Search service API URL |
+| api_key | string | Yes | API key |
+| custom_headers | table | No | Custom HTTP headers to attach to requests |
+
+**fetch service:**
+
+Configures web fetch service. When enabled, the FetchURL tool prioritizes using this service to fetch webpage content.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| base_url | string | Yes | Fetch service API URL |
+| api_key | string | Yes | API key |
+| custom_headers | table | No | Custom HTTP headers to attach to requests |
+
+### mcp
+
+`mcp` configures MCP client behavior.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| client.tool_call_timeout_ms | integer | 60000 | MCP tool call timeout (milliseconds) |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     YOUR CODEBASE                            │
+│  100K lines across 500 files                                 │
+└───────────────────────┬──────────────────────────────────────┘
+                        │
+                        ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    AXE-DIG ENGINE                            │
+│  5-layer analysis + semantic embeddings                      │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │
+│  │   AST   │→│  Calls  │→│   CFG   │→│   DFG   │→│  PDG   │ │
+│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────┘ │
+│                                                              │
+│  In-memory daemon: 100ms queries instead of 30s CLI spawns  │
+└───────────────────────┬──────────────────────────────────────┘
+                        │
+                        ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      AXE AGENT                               │
+│  • Understands code semantically (not just text)            │
+│  • Extracts minimal context (95% token savings)             │
+│  • Executes tools (file ops, shell, multi-agent)            │
+│  • Interactive shell UI with Ctrl+X toggle                  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**The difference:**
+- **Other tools**: Dump 100K lines → Claude figures it out → Burn tokens
+- **axe**: Extract 5K tokens of pure signal → Surgical edits → Save money
+
+## Advanced features
+
+### Multi-agent workflows
+Spawn subagents for parallel tasks:
+
+```bash
+# Main agent delegates to specialists
+Task "refactor auth module" --agent refactor-specialist
+Task "update tests" --agent test-specialist
+Task "update docs" --agent docs-specialist
+```
+
+### Skills system
+Reusable workflows and domain expertise:
+
+```bash
+# Available skills auto-detected from project
+/skill:docker-deploy
+/skill:api-design
+/skill:performance-optimization
+```
+
+### Context management
+axe maintains conversation history and can checkpoint/restore:
+
+```bash
+# Save current context
+/checkpoint "before-refactor"
+
+# Restore if things go wrong
+/restore "before-refactor"
+```
+
+## MCP Integration
+
+For AI tools integration, axe supports Model Context Protocol (MCP).
+
+**Add to your MCP-compatible tool's configuration:**
+
+```json
+{
+  "mcpServers": {
+    "axe-dig": {
+      "command": "dig-mcp",
+      "args": ["--project", "/path/to/your/project"]
+    }
+  }
+}
+```

axe_cli/agents/README.md

@@ -0,0 +1,160 @@
+# Agents and Subagents
+
+An agent defines the AI's behavior, including system prompts, available tools, and subagents. You can use built-in agents or create custom agents.
+
+## Lethal Efficiency with Dynamic Subagents
+
+axe isn't limited to one main agent. You can create subagents and tasks for *anything* you want.
+
+Need a dedicated security researcher? A ruthlessly precise code reviewer? A creative copywriter? axe can create and deploy specialized subagents based on your exact requirements. These subagents help you complete tasks better, faster, and more efficiently—operating with lethal precision to divide and conquer complex workflows.
+
+## Built-in agents
+
+axe provides two built-in agents. You can select one at startup with the `--agent` flag:
+
+```bash
+axe --agent default
+```
+
+**default**
+
+The default agent, suitable for general use. Enabled tools:
+
+- Task, SetTodoList, Shell, ReadFile, ReadMediaFile, Glob, Grep, WriteFile, StrReplaceFile
+- CodeSearch, CodeContext, CodeStructure, CodeImpact (axe-dig tools)
+
+**okabe**
+
+An experimental agent for testing new prompts and tools. Adds SendDMail on top of default.
+
+## Custom agent files
+
+Agents are defined in YAML format. Load a custom agent with the `--agent-file` flag:
+
+```bash
+axe --agent-file /path/to/my-agent.yaml
+```
+
+**Basic structure:**
+
+```yaml
+version: 1
+agent:
+  name: my-agent
+  system_prompt_path: ./system.md
+  tools:
+    - "axe_cli.tools.shell:Shell"
+    - "axe_cli.tools.file:ReadFile"
+    - "axe_cli.tools.file:WriteFile"
+```
+
+**Inheritance and overrides:**
+
+Use `extend` to inherit another agent's configuration and only override what you need to change:
+
+```yaml
+version: 1
+agent:
+  extend: default  # Inherit from default agent
+  system_prompt_path: ./my-prompt.md  # Override system prompt
+  exclude_tools:  # Exclude certain tools
+    - "axe_cli.tools.web:SearchWeb"
+    - "axe_cli.tools.web:FetchURL"
+```
+
+`extend: default` inherits from the built-in default agent. You can also specify a relative path to inherit from another agent file.
+
+**Configuration fields:**
+
+| Field | Description | Required |
+|-------|-------------|----------|
+| extend | Agent to inherit from, can be `default` or a relative path | No |
+| name | Agent name | Yes (optional when inheriting) |
+| system_prompt_path | System prompt file path, relative to agent file | Yes (optional when inheriting) |
+| system_prompt_args | Custom arguments passed to system prompt, merged when inheriting | No |
+| tools | Tool list, format is `module:ClassName` | Yes (optional when inheriting) |
+| exclude_tools | Tools to exclude | No |
+| subagents | Subagent definitions | No |
+
+### System prompt built-in parameters
+
+The system prompt file is a Markdown template that can use `${VAR}` syntax to reference variables. Built-in variables include:
+
+| Variable | Description |
+|----------|-------------|
+| ${AXE_NOW} | Current time (ISO format) |
+| ${AXE_WORK_DIR} | Working directory path |
+| ${AXE_WORK_DIR_LS} | Working directory file list |
+| ${AXE_AGENTS_MD} | AGENTS.md file content (if exists) |
+| ${AXE_SKILLS} | Loaded skills list |
+
+You can also define custom parameters via `system_prompt_args`:
+
+```yaml
+agent:
+  system_prompt_args:
+    MY_VAR: "custom value"
+```
+
+Then use `${MY_VAR}` in the prompt.
+
+**System prompt example:**
+
+```markdown
+# My Agent
+
+You are a helpful assistant. Current time: ${AXE_NOW}.
+
+Working directory: ${AXE_WORK_DIR}
+
+${MY_VAR}
+```
+
+### Defining subagents in agent files
+
+Subagents can handle specific types of tasks. After defining subagents in an agent file, the main agent can launch them via the Task tool:
+
+```yaml
+version: 1
+agent:
+  extend: default
+  subagents:
+    coder:
+      path: ./coder-sub.yaml
+      description: "Handle coding tasks"
+    reviewer:
+      path: ./reviewer-sub.yaml
+      description: "Code review expert"
+```
+
+Subagent files are also standard agent format, typically inheriting from the main agent and excluding certain tools:
+
+```yaml
+# coder-sub.yaml
+version: 1
+agent:
+  extend: ./agent.yaml  # Inherit from main agent
+  system_prompt_args:
+    ROLE_ADDITIONAL: |
+      You are now running as a subagent...
+  exclude_tools:
+    - "axe_cli.tools.multiagent:Task"  # Exclude Task tool to avoid nesting
+```
+
+### How subagents run
+
+Subagents launched via the Task tool run in an isolated context and return results to the main agent when complete. Advantages of this approach:
+
+- Isolated context, avoiding pollution of main agent's conversation history
+- Multiple independent tasks can be processed in parallel
+- Subagents can have targeted system prompts
+
+### Dynamic subagent creation
+
+CreateSubagent is an advanced tool that allows AI to dynamically define new subagent types at runtime (not enabled by default). To use it, add to your agent file:
+
+```yaml
+agent:
+  tools:
+    - "axe_cli.tools.multiagent:CreateSubagent"
+```

axe_cli/agents/default/system.md

@@ -20,20 +20,28 @@ When responding to the user, you MUST use the SAME language as the user, unless
 
 # Code Intelligence Tools (Axe-Dig)
 
-The codebase is automatically indexed on startup using axe-dig, providing powerful semantic code search and analysis capabilities. When working with code, **YOU MUST PREFER** these tools over basic file operations:
+The codebase is automatically indexed on startup using axe-dig. When searching for code, **Grep** is **MOST PREFERABLE** for exact results, but **CodeSearch** can be used alongside it to form a **POWERFUL COMBINATION** of semantic and exact search.
 
 **Recommended workflow for code tasks:**
-1. **CodeSearch** - Find what you're looking for (semantic discovery)
-2. **Grep** - Get exact file location and line numbers  
+1. **Grep** - PREFERRED. Use this first to find code locations.
+2. **CodeSearch** - Use in combination with Grep for semantic discovery.
 3. **CodeImpact** - Understand the function and shows all callers and dependencies, for refactoring (if needed)
 4. **StrReplaceFile** - Make precise edits
 
 ## When to use Code Intelligence tools:
 
 - **CodeSearch**: Use this **HEAVILY** for natural language queries to find code by BEHAVIOR or PURPOSE (e.g., "find where subagents are created").
-  - **Much better than Grep** for finding code based on what it does, even if you don't know the exact variable names.
+  - for finding code based on what it does, even if you don't know the exact variable names.
   - Returns semantic matches even without exact text matches.
   - Usage: `chop semantic search "natural language query"`
+  
+  **When to use CodeSearch:**
+  - Finding code by behavior: "cache with TTL", "validate input", "retry logic"
+  - Exploring unfamiliar code: "session management", "error handling patterns"
+  - Before refactoring: "who implements this pattern?"
+
+  
+  **Scores 0.65-0.80 are excellent matches. Use CodeSearch together with Grep for a powerful search strategy.**
 
 - **CodeContext**: Use when you need to understand a specific function, class, or symbol WITHOUT reading entire files.
   - **Requires a function/symbol name** (often found via CodeSearch first).
@@ -54,11 +62,47 @@ The codebase is automatically indexed on startup using axe-dig, providing powerf
   - Can be used after CodeSearch to pinpoint exact locations for StrReplaceFile.
   - Supports literal strings and complex regex patterns.
   - Returns file paths + line numbers + content.
+  
 - **ReadFile**: Reading full file content when detailed implementation logic is needed.
 - **FileSearch**: Finding files by name patterns.
 
 **Important**: The codebase is indexed automatically. You don't need to run any indexing commands.
 
+## Semantic Search Best Practices
+
+CodeSearch uses vector embeddings that capture code BEHAVIOR, not just syntax. Each function is embedded with:
+- Function signatures and docstrings
+- Call graphs (what it calls, who calls it)
+- Complexity metrics (branches, loops, cyclomatic complexity)
+- Data flow patterns (variable usage and transformations)
+- Dependencies (imports, external modules)
+- First ~10 lines of code
+
+This means you can find code by BEHAVIOR even without exact keywords:
+- ✅ "reset statistics counter" finds `reset_step_count()` (word "statistics" not in code)
+- ✅ "retry with backoff" finds `_is_retryable_error()` (word "backoff" not in function name)
+- ✅ "load TOML config" finds `load_config_from_string()` (0.76 score - near perfect!)
+- ✅ "execute shell and capture output" finds `run_sh()` which returns `(returncode, stdout, stderr)`
+
+**How to write effective queries:**
+1. Describe WHAT the code does, not HOW: "cache data with expiration" not "redis.setex"
+2. Be specific but natural: "retry with exponential backoff" finds retry logic better than just "retry"
+3. Use behavioral terms: "validate and sanitize input", "handle connection errors", "parse configuration"
+4. Scores 0.65+ are excellent, 0.55-0.65 are good, below 0.55 try rephrasing
+
+**Recommended workflow:**
+1. **Grep** - PREFERABLY, use this first to locate code.
+2. **CodeSearch** - Use if Grep fails or for behavioral search. Combine with Grep for best results.
+3. **CodeContext** - Understand the function without reading entire files
+4. **CodeImpact** - Check who calls it before refactoring
+5. **StrReplaceFile** - Make the changes
+
+**Each tool has its strength:**
+- **CodeSearch**: Discovery by behavior (best for "what does X?")
+- **Grep**: Exact text matching (best for "where is this string?")
+- **CodeContext**: Understanding without reading files (best for "how does X work?")
+- **CodeImpact**: Dependency analysis (best for "who uses X?")
+
 # General Guidelines for Coding
 
 When building something from scratch, you should:

axe_cli/app.py

@@ -108,16 +108,19 @@ class AxeCLI:
 
         model: LLMModel | None = None
         provider: LLMProvider | None = None
+        model_config_name: str | None = None
 
         # try to use config file
         if not model_name and config.default_model:
             # no --model specified && default model is set in config
             model = config.models[config.default_model]
             provider = config.providers[model.provider]
+            model_config_name = config.default_model
         if model_name and model_name in config.models:
             # --model specified && model is set in config
             model = config.models[model_name]
             provider = config.providers[model.provider]
+            model_config_name = model_name
 
         if not model:
             model = LLMModel(provider="", model="", max_context_size=100_000)
@@ -142,7 +145,7 @@ class AxeCLI:
             logger.info("Using LLM model: {model}", model=model)
             logger.info("Thinking mode: {thinking}", thinking=thinking)
 
-        runtime = await Runtime.create(config, llm, session, yolo, skills_dir)
+        runtime = await Runtime.create(config, llm, model_config_name, session, yolo, skills_dir)
 
         if agent_file is None:
             agent_file = DEFAULT_AGENT_FILE
@@ -152,17 +155,19 @@ class AxeCLI:
         await context.restore()
 
         soul = AxeSoul(agent, context=context)
-        return AxeCLI(soul, runtime, env_overrides)
+        return AxeCLI(soul, runtime, env_overrides, model)
 
     def __init__(
         self,
         _soul: AxeSoul,
         _runtime: Runtime,
         _env_overrides: dict[str, str],
+        _model_config: LLMModel | None = None,
     ) -> None:
         self._soul = _soul
         self._runtime = _runtime
         self._env_overrides = _env_overrides
+        self._model_config = _model_config
 
     @property
     def soul(self) -> AxeSoul:
@@ -288,7 +293,7 @@ class AxeCLI:
             welcome_info.append(
                 WelcomeInfoItem(
                     name="Model",
-                    value=model_display_name(self._soul.model_name),
+                    value=model_display_name(self._model_config or self._soul.model_name),
                     level=WelcomeInfoItem.Level.INFO,
                 )
             )

axe_cli/auth/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+AXE_CODE_PLATFORM_ID = "axe-code"

axe_cli/config.py

@@ -14,6 +14,14 @@ from axe_cli.share import get_share_dir
 from axe_cli.utils.logging import logger
 
 
+class OAuthRef(BaseModel):
+    storage: Literal["keyring", "file"]
+    key: str
+
+    def __hash__(self):
+        return hash((self.storage, self.key))
+
+
 class LLMProvider(BaseModel):
     """LLM provider configuration."""
 
@@ -27,6 +35,8 @@ class LLMProvider(BaseModel):
     """Environment variables to set before creating the provider instance"""
     custom_headers: dict[str, str] | None = None
     """Custom headers to include in API requests"""
+    oauth: OAuthRef | None = None
+    """OAuth configuration"""
     reasoning_key: str | None = None
     """Key name for reasoning/thinking content in API responses (e.g., 'reasoning' for OpenRouter)."""
 
@@ -42,6 +52,8 @@ class LLMModel(BaseModel):
     """Provider name"""
     model: str
     """Model name"""
+    alias: str | None = None
+    """Model alias for nickname switch"""
     max_context_size: int
     """Maximum context size (unit: tokens)"""
     capabilities: set[ModelCapability] | None = None

axe_cli/llm.py

@@ -45,10 +45,13 @@ class LLM:
         return self.chat_provider.model_name
 
 
-def model_display_name(model_name: str | None) -> str:
-    if not model_name:
+def model_display_name(model: LLMModel | str | None) -> str:
+    """Get display name for a model, using alias if available."""
+    if model is None:
         return ""
-    return model_name
+    if isinstance(model, str):
+        return model
+    return model.alias or model.model
 
 
 def augment_provider_with_env_vars(provider: LLMProvider, model: LLMModel) -> dict[str, str]: