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

axe_cli/skills/README.md

@@ -0,0 +1,242 @@
+# Agent Skills
+
+Agent Skills is an open format for adding specialized knowledge and workflows to AI agents. axe supports loading Agent Skills to extend AI capabilities.
+
+## What are Agent Skills?
+
+A skill is a directory containing a `SKILL.md` file. When axe starts, it discovers all skills and injects their names, paths, and descriptions into the system prompt. The AI will decide on its own whether to read the specific SKILL.md file to get detailed guidance based on the current task's needs.
+
+For example, you can create a "code style" skill to tell the AI your project's naming conventions, comment styles, etc.; or create a "security audit" skill to have the AI focus on specific security issues when reviewing code.
+
+## Skill discovery
+
+axe uses a layered loading mechanism to discover skills, loading in the following priority order (later ones override skills with the same name):
+
+**Built-in skills**
+
+Skills shipped with the package, providing basic capabilities.
+
+**User-level skills**
+
+Stored in the user's home directory, effective across all projects. axe checks the following directories in priority order and uses the first one that exists:
+
+- `~/.config/agents/skills/` (recommended)
+- `~/.agents/skills/`
+- `~/.axe/skills/`
+- `~/.claude/skills/`
+- `~/.codex/skills/`
+
+**Project-level skills**
+
+Stored in the project directory, only effective within that project's working directory. axe checks the following directories in priority order and uses the first one that exists:
+
+- `.agents/skills/` (recommended)
+- `.axe/skills/`
+- `.claude/skills/`
+- `.codex/skills/`
+
+You can also specify other directories with the `--skills-dir` flag, which skips user-level and project-level skill discovery:
+
+```bash
+axe --skills-dir /path/to/my-skills
+```
+
+### Built-in skills
+
+axe includes the following built-in skills:
+
+- **axe-cli-help**: axe CLI help. Answers questions about axe installation, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, and more.
+- **skill-creator**: Guide for creating skills. When you need to create a new skill (or update an existing skill) to extend axe's capabilities, you can use this skill to get detailed creation guidance and best practices.
+
+## Creating a skill
+
+Creating a skill only requires two steps:
+
+1. Create a subdirectory in the skills directory
+2. Create a SKILL.md file in the subdirectory
+
+**Directory structure:**
+
+A skill directory needs at least a SKILL.md file, and can also include auxiliary directories to organize more complex content:
+
+```
+~/.config/agents/skills/
+└── my-skill/
+    ├── SKILL.md          # Required: main file
+    ├── scripts/          # Optional: script files
+    ├── references/       # Optional: reference documents
+    └── assets/           # Optional: other resources
+```
+
+**SKILL.md format:**
+
+SKILL.md uses YAML frontmatter to define metadata, followed by prompt content in Markdown format:
+
+```yaml
+---
+name: code-style
+description: My project's code style guidelines
+---
+
+## Code Style
+
+In this project, please follow these conventions:
+
+- Use 4-space indentation
+- Variable names use camelCase
+- Function names use snake_case
+- Every function needs a docstring
+- Lines should not exceed 100 characters
+```
+
+**Frontmatter fields:**
+
+| Field | Description | Required |
+|-------|-------------|----------|
+| name | Skill name, 1-64 characters, only lowercase letters, numbers, and hyphens allowed; defaults to directory name if omitted | No |
+| description | Skill description, 1-1024 characters, explaining the skill's purpose and use cases; shows "No description provided." if omitted | No |
+| license | License name or file reference | No |
+| compatibility | Environment requirements, up to 500 characters | No |
+| metadata | Additional key-value attributes | No |
+
+**Best practices:**
+
+- Keep SKILL.md under 500 lines, move detailed content to scripts/, references/, or assets/ directories
+- Use relative paths in SKILL.md to reference other files
+- Provide clear step-by-step instructions, input/output examples, and edge case explanations
+
+### Example skills
+
+**PowerPoint creation:**
+
+```yaml
+---
+name: pptx
+description: Create and edit PowerPoint presentations
+---
+
+## PPT Creation Workflow
+
+When creating presentations, follow these steps:
+
+1. Analyze content structure, plan slide outline
+2. Choose appropriate color scheme and fonts
+3. Use python-pptx library to generate .pptx files
+
+## Design Principles
+
+- Each slide focuses on one topic
+- Keep text concise, use bullet points instead of long paragraphs
+- Maintain clear visual hierarchy with distinct titles, body, and notes
+- Use consistent colors, avoid more than 3 main colors
+```
+
+**Python project standards:**
+
+```yaml
+---
+name: python-project
+description: Python project development standards, including code style, testing, and dependency management
+---
+
+## Python Development Standards
+
+- Use Python 3.14+
+- Use ruff for code formatting and linting
+- Use pyright for type checking
+- Use pytest for testing
+- Use uv for dependency management
+
+Code style:
+- Line length limit 100 characters
+- Use type annotations
+- Public functions need docstrings
+```
+
+**Git commit conventions:**
+
+```yaml
+---
+name: git-commits
+description: Git commit message conventions using Conventional Commits format
+---
+
+## Git Commit Conventions
+
+Use Conventional Commits format:
+
+type(scope): description
+
+Allowed types: feat, fix, docs, style, refactor, test, chore
+
+Examples:
+- feat(auth): add OAuth login support
+- fix(api): fix user query returning null
+- docs(readme): update installation instructions
+```
+
+## Using slash commands to load a skill
+
+The `/skill:<name>` slash command lets you save commonly used prompt templates as skills and quickly invoke them when needed. When you enter the command, axe reads the corresponding SKILL.md file content and sends it to the Agent as a prompt.
+
+For example:
+
+- `/skill:code-style` - Load code style guidelines
+- `/skill:pptx` - Load PPT creation workflow
+- `/skill:git-commits fix user login issue` - Load Git commit conventions with an additional task description
+
+You can append additional text after the slash command, which will be added to the skill prompt as the user's specific request.
+
+**TIP:** For regular conversations, the Agent will automatically decide whether to read skill content based on context, so you don't need to invoke it manually.
+
+Skills allow you to codify your team's best practices and project standards, ensuring the AI always follows consistent standards.
+
+## Flow skills
+
+Flow skills are a special skill type that embed an Agent Flow diagram in SKILL.md, used to define multi-step automated workflows. Unlike standard skills, flow skills are invoked via `/flow:<name>` commands and automatically execute multiple conversation turns following the flow diagram.
+
+**Creating a flow skill:**
+
+To create a flow skill, set `type: flow` in the frontmatter and include a Mermaid or D2 code block in the content:
+
+```yaml
+---
+name: code-review
+description: Code review workflow
+type: flow
+---
+
+```mermaid
+flowchart TD
+A([BEGIN]) --> B[Analyze code changes, list all modified files and features]
+B --> C{Is code quality acceptable?}
+C -->|Yes| D[Generate code review report]
+C -->|No| E[List issues and propose improvements]
+E --> B
+D --> F([END])
+```
+```
+
+**Flow diagram format:**
+
+Both Mermaid and D2 formats are supported:
+
+- **Mermaid**: Use ` ```mermaid ` code block, [Mermaid Playground](https://mermaid.live) can be used for editing and preview
+- **D2**: Use ` ```d2 ` code block, [D2 Playground](https://play.d2lang.com) can be used for editing and preview
+
+Flow diagrams must contain one BEGIN node and one END node. Regular node text is sent to the Agent as a prompt; decision nodes require the Agent to output `<choice>branch name</choice>` in the output to select the next step.
+
+**Executing a flow skill:**
+
+Flow skills can be invoked in two ways:
+
+- `/flow:<name>` - Execute the flow. The Agent will start from the BEGIN node and process each node according to the flow diagram definition until reaching the END node
+- `/skill:<name>` - Like a standard skill, sends the SKILL.md content to the Agent as a prompt (does not automatically execute the flow)
+
+```bash
+# Execute the flow
+/flow:code-review
+
+# Load as a standard skill
+/skill:code-review
+```

axe_cli/soul/agent.py

@@ -64,6 +64,7 @@ class Runtime:
 
     config: Config
     llm: LLM | None  # we do not freeze the `Runtime` dataclass because LLM can be changed
+    model_config_name: str | None  # name of the model config from config.toml
     session: Session
     builtin_args: BuiltinSystemPromptArgs
     denwa_renji: DenwaRenji
@@ -71,11 +72,12 @@ class Runtime:
     labor_market: LaborMarket
     environment: Environment
     skills: dict[str, Skill]
+    oauth: OAuthManager
 
-    @staticmethod
     async def create(
         config: Config,
         llm: LLM | None,
+        model_config_name: str | None,
         session: Session,
         yolo: bool,
         skills_dir: KaosPath | None = None,
@@ -100,9 +102,12 @@ class Runtime:
             for skill in skills
         )
 
+        from axe_cli.auth.oauth import OAuthManager
+
         return Runtime(
             config=config,
             llm=llm,
+            model_config_name=model_config_name,
             session=session,
             builtin_args=BuiltinSystemPromptArgs(
                 AXE_NOW=datetime.now().astimezone().isoformat(),
@@ -116,6 +121,7 @@ class Runtime:
             labor_market=LaborMarket(),
             environment=environment,
             skills=skills_by_name,
+            oauth=OAuthManager(config),
         )
 
     def copy_for_fixed_subagent(self) -> Runtime:
@@ -123,6 +129,7 @@ class Runtime:
         return Runtime(
             config=self.config,
             llm=self.llm,
+            model_config_name=self.model_config_name,
             session=self.session,
             builtin_args=self.builtin_args,
             denwa_renji=DenwaRenji(),  # subagent must have its own DenwaRenji
@@ -130,6 +137,7 @@ class Runtime:
             labor_market=LaborMarket(),  # fixed subagent has its own LaborMarket
             environment=self.environment,
             skills=self.skills,
+            oauth=self.oauth,
         )
 
     def copy_for_dynamic_subagent(self) -> Runtime:
@@ -137,6 +145,7 @@ class Runtime:
         return Runtime(
             config=self.config,
             llm=self.llm,
+            model_config_name=self.model_config_name,
             session=self.session,
             builtin_args=self.builtin_args,
             denwa_renji=DenwaRenji(),  # subagent must have its own DenwaRenji
@@ -144,6 +153,7 @@ class Runtime:
             labor_market=self.labor_market,  # dynamic subagent shares LaborMarket with main agent
             environment=self.environment,
             skills=self.skills,
+            oauth=self.oauth,
         )
 
 

axe_cli/soul/axesoul.py

@@ -133,6 +133,16 @@ class AxeSoul:
     def model_name(self) -> str:
         return self._runtime.llm.chat_provider.model_name if self._runtime.llm else ""
 
+    @property
+    def model_display_name(self) -> str:
+        """Get the display name for the model (uses alias if available)."""
+        if self._runtime.llm is None:
+            return ""
+        if self._runtime.model_config_name and self._runtime.model_config_name in self._runtime.config.models:
+            model_cfg = self._runtime.config.models[self._runtime.model_config_name]
+            return model_cfg.alias or model_cfg.model
+        return self._runtime.llm.chat_provider.model_name
+
     @property
     def model_capabilities(self) -> set[ModelCapability] | None:
         if self._runtime.llm is None:

axe_cli/tools/README.md

@@ -0,0 +1,135 @@
+# Built-in Tools
+
+The following are all built-in tools in axe.
+
+## Task
+**Path:** `axe_cli.tools.multiagent:Task`  
+**Description:** Dispatch a subagent to execute a task. Subagents cannot access the main agent's context; all necessary information must be provided in the prompt.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| description | string | Short task description (3-5 words) |
+| subagent_name | string | Subagent name |
+| prompt | string | Detailed task description |
+
+## SetTodoList
+**Path:** `axe_cli.tools.todo:SetTodoList`  
+**Description:** Manage todo list, track task progress
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| todos | array | Todo list items |
+| todos[].title | string | Todo item title |
+| todos[].status | string | Status: pending, in_progress, done |
+
+## Shell
+**Path:** `axe_cli.tools.shell:Shell`  
+**Description:** Execute shell commands. Requires user approval. Uses the appropriate shell for the OS (bash/zsh on Unix, PowerShell on Windows).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| command | string | Command to execute |
+| timeout | int | Timeout in seconds, default 60, max 300 |
+
+## ReadFile
+**Path:** `axe_cli.tools.file:ReadFile`  
+**Description:** Read text file content. Max 1000 lines per read, max 2000 characters per line. Files outside working directory require absolute paths.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| path | string | File path |
+| line_offset | int | Starting line number, default 1 |
+| n_lines | int | Number of lines to read, default/max 1000 |
+
+## ReadMediaFile
+**Path:** `axe_cli.tools.file:ReadMediaFile`  
+**Description:** Read image or video files. Max file size 100MB. Only available when the model supports image/video input. Files outside working directory require absolute paths.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| path | string | File path |
+
+## Glob
+**Path:** `axe_cli.tools.file:Glob`  
+**Description:** Match files and directories by pattern. Returns max 1000 matches, patterns starting with ** not allowed.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| pattern | string | Glob pattern (e.g., *.py, src/**/*.ts) |
+| directory | string | Search directory, defaults to working directory |
+| include_dirs | bool | Include directories, default true |
+
+## Grep
+**Path:** `axe_cli.tools.file:Grep`  
+**Description:** Search file content with regular expressions, based on ripgrep
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| pattern | string | Regular expression pattern |
+| path | string | Search path, defaults to current directory |
+| glob | string | File filter (e.g., *.js) |
+| type | string | File type (e.g., py, js, go) |
+| output_mode | string | Output mode: files_with_matches (default), content, count_matches |
+| -B | int | Show N lines before match |
+| -A | int | Show N lines after match |
+| -C | int | Show N lines before and after match |
+| -n | bool | Show line numbers |
+| -i | bool | Case insensitive |
+| multiline | bool | Enable multiline matching |
+| head_limit | int | Limit output lines |
+
+## WriteFile
+**Path:** `axe_cli.tools.file:WriteFile`  
+**Description:** Write files. Requires user approval. Absolute paths are required when writing files outside the working directory.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| path | string | Absolute path |
+| content | string | File content |
+| mode | string | overwrite (default) or append |
+
+## StrReplaceFile
+**Path:** `axe_cli.tools.file:StrReplaceFile`  
+**Description:** Edit files using string replacement. Requires user approval. Absolute paths are required when editing files outside the working directory.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| path | string | Absolute path |
+| edit | object/array | Single edit or list of edits |
+| edit.old | string | Original string to replace |
+| edit.new | string | Replacement string |
+| edit.replace_all | bool | Replace all matches, default false |
+
+## CodeSearch
+**Path:** `axe_cli.tools.axe:CodeSearch`  
+**Description:** Semantic code search powered by axe-dig. Finds code by behavior, not just text matches.
+
+## CodeContext
+**Path:** `axe_cli.tools.axe:CodeContext`  
+**Description:** Get LLM-ready function summaries with 95% token savings.
+
+## CodeStructure
+**Path:** `axe_cli.tools.axe:CodeStructure`  
+**Description:** Navigate functions and classes in files or directories.
+
+## CodeImpact
+**Path:** `axe_cli.tools.axe:CodeImpact`  
+**Description:** Reverse call graph analysis - see who calls a function before refactoring.
+
+## Tool security boundaries
+
+**Working directory restrictions:**
+
+- File reading and writing are typically done within the working directory
+- Absolute paths are required when reading files outside the working directory
+- Write and edit operations require user approval; absolute paths are required when operating on files outside the working directory
+
+**Approval mechanism:**
+
+The following operations require user approval:
+
+| Operation | Approval required |
+|-----------|-------------------|
+| Shell command execution | Each execution |
+| File write/edit | Each operation |
+| MCP tool calls | Each call |

axe_cli/tools/axe/auto_init.py

@@ -142,14 +142,14 @@ def prompt_user_for_init(work_dir: Path) -> tuple[bool, str]:
     """
     console.print()
     console.print(Panel.fit(
-        "[bold cyan]okay so, lets pre-warm your codebase![/bold cyan]\n\n"
+        "[bold]okay so, lets pre-warm your codebase![/bold]\n\n"
         "this builds the analysis stack once.\n"
         "after completion, queries are instant and the daemon handles everything.\n\n"
         "[dim]parsing structure. building call graphs. computing dependencies. encoding semantics.[/dim]\n\n"
-        "axe-dig gives llms [bold]lethal precision.[/bold]\n"
+        "axe-dig gives llms [bold red]lethal precision.[/bold red]\n"
         "natural language queries. [bold]exact context.[/bold] 95% fewer tokens.\n\n"
         "takes two minutes for typical projects.",
-        border_style="cyan"
+        border_style="white"
     ))
     console.print()
     console.print(f"[dim]this is the directory we gonna work with: {work_dir}[/dim]")
@@ -165,14 +165,14 @@ def prompt_user_for_init(work_dir: Path) -> tuple[bool, str]:
     
     console.print()
     console.print("[bold]choose digging depth:[/bold]\n")
-    console.print("  [cyan]1)[/cyan] [bold]light-digging[/bold] (recommended)")
+    console.print("  1) [bold]light-digging[/bold] (recommended)")
     console.print("     • 90mb download")
     console.print("     • 2gb ram during indexing")
     console.print("     • fast. ~1 min for medium projects")
     console.print("     • good precision for most codebases")
     console.print("     • finds: 'jwt validation' → verify_token()")
     console.print()
-    console.print("  [cyan]2)[/cyan] [bold]heavy-digging[/bold] (maximum precision)")
+    console.print("  2) [bold]heavy-digging[/bold] (maximum precision)")
     console.print("     • 1.3gb download")
     console.print("     • 10gb+ ram during indexing")
     console.print("     • slower. 5-15 min for medium projects")
@@ -189,7 +189,7 @@ def prompt_user_for_init(work_dir: Path) -> tuple[bool, str]:
     model = "minilm" if choice == "1" else "bge-large"
     model_display = "light-digging (sentence-transformers/all-MiniLM-L6-v2)" if model == "minilm" else "heavy-digging (BAAI/bge-large-en-v1.5)"
     
-    console.print(f"\n[dim]selected: {model_display}[/dim]")
+    console.print(f"\n[dim]selected:[/dim] [red]{model_display}[/red]")
     return True, model
 
 
@@ -236,9 +236,9 @@ async def auto_initialize_codebase(work_dir: Path, model: str | None = None, int
     
     console.print()
     console.print(Panel.fit(
-        "[bold cyan]okay lets do this!, grab a coffee—- axe is now understanding your codebase![/bold cyan]\n"
+        "[bold]okay lets do this!, grab a coffee—- axe is now understanding your codebase![/bold]\n"
         f"[dim]Model: {model_name}[/dim]",
-        border_style="cyan"
+        border_style="white"
     ))
     console.print()
     
@@ -246,67 +246,67 @@ async def auto_initialize_codebase(work_dir: Path, model: str | None = None, int
     create_dig_config(work_dir, model)
     
     with Progress(
-        SpinnerColumn(),
+        SpinnerColumn(style="bold red"),
         TextColumn("[progress.description]{task.description}"),
-        BarColumn(),
+        BarColumn(bar_width=None, style="dim white", complete_style="white", finished_style="white"),
         TaskProgressColumn(),
         console=console,
         transient=False
     ) as progress:
         
         # Step 1: Structural indexing
-        task1 = progress.add_task("[cyan]Building structural index and understanding the structure to see what's up...", total=100)
+        task1 = progress.add_task("building and understanding the structure..", total=100)
         progress.update(task1, advance=10)
         
         success, output = await run_chop_command(f"chop warm {work_dir}", work_dir)
         
         if success:
-            progress.update(task1, advance=90, description="[green]✓ structure indexed")
+            progress.update(task1, advance=90, description="[bold]✓ structure indexed[/bold]")
             for line in output.split("\n"):
                 if "Indexed" in line and "files" in line:
                     console.print(f"  [dim]{line}[/dim]")
         else:
-            progress.update(task1, description="[red]✗structural indexing failed")
+            progress.update(task1, description="[red]✗structural indexing failed[/red]")
             console.print(f"  [red]{output[:200]}[/red]")
             return
         
         # Step 2: Semantic indexing
-        task2 = progress.add_task("[cyan]building semantics...", total=100)
+        task2 = progress.add_task("building semantics...", total=100)
         progress.update(task2, advance=10)
         
         cmd = f"chop semantic index {work_dir} --model {model_name}"
         success, output = await run_chop_command(cmd, work_dir, timeout=1800)
         
         if success:
-            progress.update(task2, advance=90, description="[green]✓ ok, semantic index built")
+            progress.update(task2, advance=90, description="[bold]✓ ok, semantic index built[/bold]")
             for line in output.split("\n"):
                 if "Indexed" in line and "code units" in line:
                     console.print(f"  [dim]{line}[/dim]")
         else:
-            progress.update(task2, description="[yellow]⚠ semantic indexing failed due to some reason, maybe try again?")
-            console.print(f"  [yellow]{output[:200]}[/yellow]")
+            progress.update(task2, description="[red]⚠ semantic indexing failed due to some reason, maybe try again?[/red]")
+            console.print(f"  [red]{output[:200]}[/red]")
         
         # Step 3: Start daemon
-        task3 = progress.add_task("[cyan]starting daemon...", total=100)
+        task3 = progress.add_task("starting daemon...", total=100)
         progress.update(task3, advance=10)
         
         success, output = await run_chop_command(f"chop daemon start --project {work_dir}", work_dir, timeout=30)
         
         if success or "already running" in output.lower():
-            progress.update(task3, advance=90, description="[green]daemon active")
+            progress.update(task3, advance=90, description="[bold]daemon active[/bold]")
         else:
-            progress.update(task3, description="[yellow]⚠ umm, daemon skipped")
+            progress.update(task3, description="[red]⚠ umm, daemon skipped[/red]")
             console.print(f"  [dim]you can run 'chop daemon start --project {work_dir}' manually if needed[/dim]")
     
     console.print()
     console.print(Panel.fit(
-        "[bold green]axe ready[/bold green]\n\n"
+        "[bold]axe ready[/bold]\n\n"
         "[dim]tools available:[/dim]\n"
-        "  • [cyan]codesearch[/cyan] - semantic search by behavior\n"
-        "  • [cyan]codecontext[/cyan] - precise function context\n"
-        "  • [cyan]codeimpact[/cyan] - reverse call graph\n"
-        "  • [cyan]codestructure[/cyan] - function and class maps",
-        border_style="green"
+        "  • codesearch - semantic search by behavior\n"
+        "  • codecontext - precise function context\n"
+        "  • codeimpact - reverse call graph\n"
+        "  • codestructure - function and class maps",
+        border_style="white"
     ))
     console.print()
 
@@ -331,4 +331,4 @@ async def ensure_codebase_initialized(work_dir: Path) -> None:
     try:
         await auto_initialize_codebase(work_dir, model=None, interactive=interactive)
     except Exception as e:
-        console.print(f"[yellow]⚠ Axe-dig auto-init skipped: {e}[/yellow]")
+        console.print(f"[red]⚠ Axe-dig auto-init skipped: {e}[/red]")

axe_cli/tools/axe/context.py

@@ -56,11 +56,10 @@ Returns a compressed LLM-ready summary that includes:
    → calls: check_permissions, get_user_data, log_access
 ```
 
-**Why use this instead of ReadFile?**
+**Why use this?**
 - 95% fewer tokens while preserving understanding
 - Includes cross-file context (callers from other files, dependencies)
 - Shows complexity metrics to assess refactoring difficulty
-- Optimized for LLM comprehension
 
 **When to use:**
 - Understanding a function before editing it

axe_cli/tools/axe/impact.py

@@ -55,7 +55,15 @@ Shows all places that call or depend on a function/class, helping you understand
 - Finding all consumers of an API or function
 - Assessing change impact and blast radius
 
-**Output:** List of all callers with file locations and context.
+**examples:**
+```bash
+chop impact TokenCounter src/axe_cli/
+# Result: Only called by get_global_counter() in same file
+# Meaning: Safe to refactor - no external dependencies to break
+# Output shows caller_count: 1, with full call chain
+```
+
+**Output:** JSON with all callers, their locations, and the full call tree.
 
 **Note:** The codebase is automatically indexed on startup.
 

axe_cli/tools/axe/prewarm.py

@@ -28,7 +28,7 @@ class CodePrewarm(CallableTool2[CodePrewarmParams]):
     """
     PRE-WARM the codebase using axe-dig.
     
-    Runs: `chop warm` + `chop semantic index`
+    Runs: `chop warm .` + `chop semantic index .`
     
     This runs full structural analysis and builds semantic embeddings.
     Run this on any new/existing project first before using other code analysis tools.

axe_cli/tools/axe/search.py

@@ -43,11 +43,17 @@ Runs: `chop semantic search "<query>" --path <path>`
 Search by what code DOES, not just what it says. Uses vector embeddings 
 to find functions by their purpose, even without exact text matches.
 
-**Examples:**
-- "validate JWT tokens and check expiration" → finds verify_access_token()
-- "database connection pooling" → finds connection management code  
-- "recursion cycle" → finds mutually recursive functions
-- "error handling for API requests" → finds exception handlers
+** examples :**
+- "retry failed operations with exponential backoff" → _is_retryable_error() (score: 0.71)
+- "load configuration from toml file" → load_config_from_string() (score: 0.76)
+- "execute shell commands and capture output" → run_sh() (score: 0.73)
+- "write content to file and handle errors" → flush_content() (score: 0.69)
+
+**How to write good queries:**
+- Describe WHAT the code does, not HOW: "cache data with expiration" not "redis.setex"
+- Be specific but natural: "retry with backoff" finds retry logic better than just "retry"
+- Use behavioral terms: "validate input", "handle errors", "parse config"
+- Scores 0.65+ are excellent, 0.55-0.65 are good, below 0.55 try different terms
 
 **Result format:** Returns function names with relevance scores (0-1).