diff --git a/cecli/__init__.py b/cecli/__init__.py index 000258ef690..29a2d797be6 100644 --- a/cecli/__init__.py +++ b/cecli/__init__.py @@ -1,6 +1,6 @@ from packaging import version -__version__ = "1.0.3.dev" +__version__ = "1.0.5.dev" safe_version = __version__ try: diff --git a/cecli/coders/agent_coder.py b/cecli/coders/agent_coder.py index a6951ad5771..e944f5c791f 100644 --- a/cecli/coders/agent_coder.py +++ b/cecli/coders/agent_coder.py @@ -89,7 +89,6 @@ def __init__(self, *args, **kwargs): self.file_read_cache = set() self.tool_call_count = 0 self.turn_count = 0 - self.max_reflections = 15 self.use_enhanced_context = True self._last_edited_file = None self._cur_message_divider = None diff --git a/cecli/coders/base_coder.py b/cecli/coders/base_coder.py index ecea205b025..679cba8f3e5 100755 --- a/cecli/coders/base_coder.py +++ b/cecli/coders/base_coder.py @@ -1886,6 +1886,7 @@ async def run_one(self, user_message, preproc): ConversationService.get_chunks(self).flush_removals() self.last_user_message = user_message self.error_code = None + self.num_tool_calls = 0 # Trim memory in the background so it doesn't delay the response coroutines.fire_and_forget(asyncio.to_thread(trim_memory)) # Fire memorizer after each user request diff --git a/cecli/help.py b/cecli/help.py index 338025f4415..f9cab2288d0 100755 --- a/cecli/help.py +++ b/cecli/help.py @@ -58,11 +58,22 @@ def fname_to_url(filepath): if relevant_parts and relevant_parts[0].lower() == "_includes": return "" url_path = "/".join(relevant_parts) + + # docmd renders each .md source to /index.html, so the published + # URLs are directory-style (e.g. /docs/usage/) rather than .html files. + is_doc = False if url_path.lower().endswith(index.lower()): url_path = url_path[: -len(index)] + is_doc = True elif url_path.lower().endswith(md.lower()): - url_path = url_path[: -len(md)] + ".html" + url_path = url_path[: -len(md)] + is_doc = True + url_path = url_path.strip("/") + if not url_path: + return "https://cecli.dev/" + if is_doc: + return f"https://cecli.dev/{url_path}/" return f"https://cecli.dev/{url_path}" diff --git a/cecli/helpers/hashline.py b/cecli/helpers/hashline.py index cb2441b3419..f344332b40c 100644 --- a/cecli/helpers/hashline.py +++ b/cecli/helpers/hashline.py @@ -382,6 +382,20 @@ def _resolve_to_hash_id(lines, idx, hp): key=lambda idx: abs(idx - start_hint_line), ) resolved_start = _resolve_to_hash_id(lines, resolved_start_idx, hp) + else: + # Fallback: the value may be line content whose whitespace was + # normalized (e.g. stripped indentation). Resolve it against a + # single unique line — mirroring apply_hashline_operations — so + # the preview resolves exactly like the actual edit. + unique_resolved = _try_resolve_as_unique_line(hp, first_line) + if unique_resolved is not None: + resolved_start = unique_resolved + try: + candidates = hp.resolve_to_lines(normalize_hashline(unique_resolved)) + if candidates: + resolved_start_idx = candidates[0] + except (ContentHashError, ValueError): + pass elif start_value is not None and _looks_like_content_id(start_value): # Already a content ID - try to resolve it to find the line position # for proximity matching with end_value @@ -432,6 +446,14 @@ def _resolve_to_hash_id(lines, idx, hp): key=lambda idx: abs(idx - resolved_start_idx), ) resolved_end = _resolve_to_hash_id(lines, closest_idx, hp) + else: + # Fallback: the value may be line content whose whitespace was + # normalized (e.g. stripped indentation). Resolve it against a + # single unique line — mirroring apply_hashline_operations — so + # the preview resolves exactly like the actual edit. + unique_resolved = _try_resolve_as_unique_line(hp, first_line) + if unique_resolved is not None: + resolved_end = unique_resolved elif end_value is not None and _looks_like_content_id(end_value): # Already a content ID - try to resolve it try: diff --git a/cecli/helpers/queues.py b/cecli/helpers/queues.py index 0628bb4a39a..3f868d97812 100644 --- a/cecli/helpers/queues.py +++ b/cecli/helpers/queues.py @@ -90,10 +90,23 @@ def wake_input_waiters() -> None: Safe to call from any thread; the wake is marshaled onto the input loop via call_soon_threadsafe. No-op if no consumer has bound a loop yet. + + If the bound loop was closed (e.g. a hot reload tore down the previous + coder worker loop), the stale binding is dropped so the next + wait_for_input() rebinds to the current loop instead of raising + "Event loop is closed". """ + global _input_loop, _input_wake + loop = _input_loop if loop is None or _input_wake is None: return + + if loop.is_closed(): + _input_loop = None + _input_wake = None + return + loop.call_soon_threadsafe(_input_wake.set) @@ -102,9 +115,19 @@ async def wait_for_input() -> None: Must be called from the input loop (the coder worker loop). Consumers sweep the payload queues first, then block here until wake_input_waiters() - fires. Initializes the wake state from the running loop on first use. + fires. Initializes the wake state from the running loop on first use and + rebinds whenever the previous loop was closed or is no longer the + running loop (which happens across a hot reload). """ - if _input_loop is None or _input_wake is None: - set_input_loop(asyncio.get_running_loop()) + loop = asyncio.get_running_loop() + + if ( + _input_loop is None + or _input_wake is None + or _input_loop.is_closed() + or _input_loop is not loop + ): + set_input_loop(loop) + _input_wake.clear() await _input_wake.wait() diff --git a/cecli/tools/grep.py b/cecli/tools/grep.py index 2067ddcf134..4a3c1d66ebe 100644 --- a/cecli/tools/grep.py +++ b/cecli/tools/grep.py @@ -328,6 +328,8 @@ def execute( Returns a JSON string with structured results including per-file groupings, match counts, and summary metadata. """ + import json + if not isinstance(searches, list): response = ToolResponse(cls.NORM_NAME, result_type=cls.RESULT_TYPE) response.append_error("'searches' parameter must be an array.") @@ -553,6 +555,53 @@ def execute( all_operation_results.append(op_result) + # Cap the output size to 50k characters for the LLM + # Heuristic: Prioritize shallowness (short paths) and fewer matches + # Removal order: Longest paths first, then most matches first. + MAX_TOTAL_SIZE = 50000 + if len(json.dumps(all_operation_results)) > MAX_TOTAL_SIZE: + # Flatten files with their metadata for sorting + all_files_to_rank = [] + for op_idx, op in enumerate(all_operation_results): + for file_idx, f_data in enumerate(op.get("files", [])): + all_files_to_rank.append( + { + "op_idx": op_idx, + "file_idx": file_idx, + "path_len": len(f_data.get("file", "")), + "match_count": f_data.get("match_count", 0), + } + ) + + # Sort for REMOVAL (worst first): Longest path, then most matches + all_files_to_rank.sort(key=lambda x: (x["path_len"], x["match_count"]), reverse=True) + + # Progressively remove files until under limit + removed_set = set() + trimmed_results = all_operation_results + for rank_info in all_files_to_rank: + removed_set.add((rank_info["op_idx"], rank_info["file_idx"])) + + # Reconstruct to check size + trimmed_results = [] + for o_idx, op in enumerate(all_operation_results): + new_op = op.copy() + original_files = op.get("files", []) + new_op["files"] = [ + f + for f_idx, f in enumerate(original_files) + if (o_idx, f_idx) not in removed_set + ] + if len(new_op["files"]) < len(original_files): + new_op["has_more_files"] = True + trimmed_results.append(new_op) + + if len(json.dumps(trimmed_results)) <= MAX_TOTAL_SIZE: + all_operation_results = trimmed_results + break + else: + all_operation_results = trimmed_results + # TUI summary if coder.tui and coder.tui(): ui_summaries = [] diff --git a/cecli/tui/app.py b/cecli/tui/app.py index 6a2bba332b5..3363e52fc04 100644 --- a/cecli/tui/app.py +++ b/cecli/tui/app.py @@ -365,16 +365,18 @@ def compose(self) -> ComposeResult: "cyan2", "cyan1", "bright_white", + "medium_spring_green", ] + E = f"[bold {BANNER_COLORS[6]}]▓▓▓[/bold {BANNER_COLORS[6]}]" # ASCII banner for startup BANNER = f""" -[bold {BANNER_COLORS[0]}] ▒▒▒▒▒▒╗▒▒▒▒▒▒▒╗ ▒▒▒▒▒▒╗▒▒╗ ▒▒╗[/bold {BANNER_COLORS[0]}] -[bold {BANNER_COLORS[1]}] ▒▒╔════╝▒▒╔════╝▒▒╔════╝▒▒║ ▒▒║[/bold {BANNER_COLORS[1]}] -[bold {BANNER_COLORS[2]}] ▒▒║ ▒▒▒▒▒╗ ▒▒║ ▒▒║ ▒▒║[/bold {BANNER_COLORS[2]}] -[bold {BANNER_COLORS[3]}] ▒▒║ ▒▒╔══╝ ▒▒║ ▒▒║ ▒▒║[/bold {BANNER_COLORS[3]}] -[bold {BANNER_COLORS[4]}] ╚▒▒▒▒▒▒╗▒▒▒▒▒▒▒╗╚▒▒▒▒▒▒╗▒▒▒▒▒▒▒╗▒▒║[/bold {BANNER_COLORS[4]}] -[bold {BANNER_COLORS[5]}] ╚═════╝╚══════╝ ╚═════╝╚══════╝╚═╝ v{__version__}[/bold {BANNER_COLORS[5]}] +[bold {BANNER_COLORS[0]}] ▒▒╗▒▒╗[/bold {BANNER_COLORS[0]}] +[bold {BANNER_COLORS[1]}] ▒▒▒▒▒╗ ▒▒▒▒▒╗ ▒▒▒▒▒╗▒▒║╚═╝[/bold {BANNER_COLORS[1]}] +[bold {BANNER_COLORS[2]}] ▒▒╔═══╝▒▒{E}▒║▒▒╔═══╝▒▒║▒▒╗[/bold {BANNER_COLORS[2]}] +[bold {BANNER_COLORS[3]}] ▒▒║ ▒▒╔═══╝▒▒║ ▒▒║▒▒║[/bold {BANNER_COLORS[3]}] +[bold {BANNER_COLORS[4]}] ╚▒▒▒▒▒╗╚▒▒▒▒▒╗╚▒▒▒▒▒╗▒▒║▒▒║[/bold {BANNER_COLORS[4]}] +[bold {BANNER_COLORS[5]}] ╚════╝ ╚════╝ ╚════╝╚═╝╚═╝ v{__version__}[/bold {BANNER_COLORS[5]}] """ diff --git a/cecli/tui/worker.py b/cecli/tui/worker.py index 6ad917b8fda..babe0b14396 100644 --- a/cecli/tui/worker.py +++ b/cecli/tui/worker.py @@ -49,6 +49,14 @@ def _run_thread(self): asyncio.set_event_loop(self.loop) self.loop.set_exception_handler(self.worker_loop_exception_handler) + # Bind the global input wake-up state to this worker loop so + # producers (TUI, WebSocket, ACP) wake consumers on the correct + # loop. A fresh binding is required after a hot reload, where the + # previous worker loop was closed. + from cecli.helpers import queues + + queues.set_input_loop(self.loop) + try: self.loop.run_until_complete(self._async_run()) except BaseException: diff --git a/cecli/urls.py b/cecli/urls.py index 9a5c44c0593..f5cb615774e 100644 --- a/cecli/urls.py +++ b/cecli/urls.py @@ -1,14 +1,14 @@ website = "https://cecli.dev/" -edit_errors = "https://cecli.dev/docs/troubleshooting/edit-errors.html" -git = "https://cecli.dev/docs/git.html" -enable_playwright = "https://cecli.dev/docs/usage/optional.html#enable-playwright" +edit_errors = "https://cecli.dev/docs/troubleshooting/edit-errors/" +git = "https://cecli.dev/docs/git/" +enable_playwright = "https://cecli.dev/docs/usage/optional/#enable-playwright" favicon = "https://cecli.dev/assets/cecli-temp-logo-favicon.svg" -model_warnings = "https://cecli.dev/docs/llms/warnings.html" -token_limits = "https://cecli.dev/docs/troubleshooting/token-limits.html" -llms = "https://cecli.dev/docs/llms.html" +model_warnings = "https://cecli.dev/docs/llms/warnings/" +token_limits = "https://cecli.dev/docs/troubleshooting/token-limits/" +llms = "https://cecli.dev/docs/llms/" github_issues = "https://github.com/cecli-dev/cecli/issues/new" git_index_version = "https://github.com/Aider-AI/aider/issues/211" -install_properly = "https://cecli.dev/docs/troubleshooting/imports.html" +install_properly = "https://cecli.dev/docs/troubleshooting/imports/" release_notes = "https://github.com/cecli-dev/cecli/releases/latest" -edit_formats = "https://cecli.dev/docs/more/edit-formats.html" -models_and_keys = "https://cecli.dev/docs/troubleshooting/models-and-keys.html" +edit_formats = "https://cecli.dev/docs/more/edit-formats/" +models_and_keys = "https://cecli.dev/docs/troubleshooting/models-and-keys/" diff --git a/cecli/website/assets/styles.scss b/cecli/website/assets/styles.scss index d00fbf870b4..eac246e2cbf 100644 --- a/cecli/website/assets/styles.scss +++ b/cecli/website/assets/styles.scss @@ -88,12 +88,14 @@ a { color: var(--text); } -.nav-logo-icon { - width: 17px; - height: 17px; - color: var(--accent); +.nav-logo-mark { + display: block; + width: 24px; + height: 24px; + flex: 0 0 24px; } + .nav-links { display: flex; align-items: center; @@ -489,6 +491,7 @@ a { .footer { padding: 24px 0 28px; border-top: 1px solid var(--border); + background: #fff; } .footer-inner { diff --git a/cecli/website/docmd.config.json b/cecli/website/docmd.config.json index 22b887ad2f8..09052ed7c74 100644 --- a/cecli/website/docmd.config.json +++ b/cecli/website/docmd.config.json @@ -20,7 +20,11 @@ { "title": "Configuration", "path": "/config/" - }, + }, + { + "title": "API Keys", + "path": "/config/api-keys/" + }, { "title": "Usage", "path": "/usage/" @@ -34,8 +38,20 @@ { "title": "Configuration", "icon": "settings", - "path": "/config/", + "collapsible": true, "children": [ + { + "title": "Config - YAML (Preferred)", + "path": "/config/conf/" + }, + { + "title": "Config - .env", + "path": "/config/dotenv/" + }, + { + "title": "Config - CLI", + "path": "/config/options/" + }, { "title": "Agent Mode", "path": "/config/agent-mode/" @@ -43,27 +59,11 @@ { "title": "Agent Memory", "path": "/config/persistent-memory/" - }, - { - "title": "API Keys", - "path": "/config/api-keys/" }, { "title": "Agent Client Protocol (ACP)", "path": "/config/api/" }, - { - "title": "Config - File", - "path": "/config/conf/" - }, - { - "title": "Config - Env. Vars", - "path": "/config/dotenv/" - }, - { - "title": "Config - CLI Options", - "path": "/config/options/" - }, { "title": "Custom Commands", "path": "/config/custom-commands/" @@ -73,7 +73,7 @@ "path": "/config/custom-system-prompts/" }, { - "title": "Editor configuration", + "title": "Editor Configuration", "path": "/config/editor/" }, { @@ -91,15 +91,15 @@ { "title": "Model Configuration Files", "path": "/config/adv-model-settings/" - }, + }, { "title": "Model Providers", "path": "/config/model-providers/" - }, + }, { "title": "Model Aliases", "path": "/config/model-aliases/" - }, + }, { "title": "Reasoning models", "path": "/config/reasoning/" @@ -113,9 +113,9 @@ "path": "/config/security/" }, { - "title": "Skills System", + "title": "Skills", "path": "/config/skills/" - }, + }, { "title": "Sub-Agents", "path": "/config/subagents/" @@ -202,7 +202,7 @@ { "title": "Other LLMs", "path": "/llms/other/" - } + } ] }, { @@ -217,21 +217,21 @@ { "title": "Session Management", "path": "/usage/sessions/" - }, + }, { "title": "Convention Files", "path": "/usage/conventions/" - }, + }, { - "title": "Images & web pages", + "title": "Images & Web Pages", "path": "/usage/images-urls/" }, { - "title": "Linting and testing", + "title": "Linting and Testing", "path": "/usage/lint-test/" }, { - "title": "Chat modes", + "title": "Chat Modes", "path": "/usage/modes/" }, { @@ -241,7 +241,7 @@ { "title": "Copy/Paste Mode", "path": "/usage/copypaste/" - }, + }, { "title": "Voice Mode", "path": "/usage/voice/" @@ -253,7 +253,7 @@ { "title": "Tips", "path": "/usage/tips/" - } + } ] }, { @@ -280,7 +280,7 @@ { "title": "Edit Formats", "path": "/more/edit-formats/" - } + } ] }, { diff --git a/cecli/website/docs/config/agent-mode.md b/cecli/website/docs/config/agent-mode.md index 29251e3ff91..065528c4118 100644 --- a/cecli/website/docs/config/agent-mode.md +++ b/cecli/website/docs/config/agent-mode.md @@ -44,22 +44,21 @@ This loop continues automatically until the `Yield` tool is called, or the maxim #### Tool Registry System -Agent Mode uses a centralized local tool registry that manages all available tools: +Agent Mode uses a centralized local tool registry. The standard tools include: -- **File Discovery Tools**: `ExploreCode`, `Ls`, `Grep` -- **Editing Tools**: `EditFile`, -- **Context Management Tools**: `ResourceManager`, `GetLines` -- **Git Tools**: `GitDiff`, `GitLog`, `GitShow`, `GitStatus` -- **Utility Tools**: `UpdateTodoList`, `UndoChange`, `Yield` -- **Sub-Agent Tools**: `Delegate` - Delegate sub-tasks to specialized sub-agents +- **Discovery and inspection**: `ExploreCode`, `Ls`, `Grep`, `ReadFile`, and `Thinking` +- **Context and editing**: `ResourceManager`, `EditFile`, `UndoChange`, and `UpdateTodoList` +- **Execution and orchestration**: `Command` and `Orchestrate` +- **Sub-agent coordination**: `Delegate` and `Yield` +- **Optional memory tools**: `SearchFacts` and `ReplaceFacts` #### Enhanced Context Management Agent Mode includes some useful context management features: - **Automatic file tracking**: Files added during exploration are tracked separately -- **Context blocks**: Directory structure, git status, symbol outlines, and environment info -- **Token management**: Automatic calculation of context usage and warnings when approaching limits +- **Configurable context blocks**: Environment, todo, skills, server, sub-agent, orchestration, and other blocks can be included or excluded +- **Token management**: Context token counts are calculated when enabled; detailed limit warnings are shown by the `context_summary` block - **Tool usage history**: Tracks repetitive tool usage to prevent exploration loops ### Key Features @@ -74,7 +73,7 @@ Agent Mode includes some useful context management features: - **Undo capability**: `UndoChange` tool for immediate recovery from mistakes - **Dry run support**: Tools can be tested with `dry_run=True` -- **Line number verification**: Two-step process for line-based edits to prevents errors +- **Virtual content IDs**: `ReadFile` returns virtual line identifiers that `EditFile` uses to target complete logical blocks safely - **Tool usage monitoring**: Prevents infinite loops by tracking repetitive patterns ### Workflow Process @@ -83,18 +82,18 @@ Agent Mode includes some useful context management features: The LLM uses discovery tools to gather information: -``` -Tool Call: ViewFilesMatching -Arguments: {"pattern": "config", "file_pattern": "*.py"} +```text +Tool Call: ExploreCode +Arguments: {"queries": [{"symbol": "Config", "action": "search"}]} -Tool Call: View -Arguments: {"file_path": "main.py"} +Tool Call: ReadFile +Arguments: {"read": [{"file_path": "main.py", "range_start": "@000", "range_end": "000@"}]} Tool Call: Grep -Arguments: {"pattern": "function_name"} +Arguments: {"searches": [{"pattern": "function_name", "directory": "."}]} ``` -Files found during exploration are added to context as read-only, allowing the LLM to analyze them without immediate editing. +`ExploreCode` uses a codebase index when available. `ReadFile` returns content with virtual identifiers for precise follow-up edits. Files discovered through agent tools can be added as read-only context by using `ResourceManager` to change context membership. #### 2. Planning Phase @@ -107,68 +106,74 @@ Arguments: {"content": "## Task: Add new feature\n- [ ] Analyze existing code\n- #### 3. Execution Phase -Files are made editable and modifications are applied: - -``` -Tool Call: MakeEditable -Arguments: {"file_path": "main.py"} +Files are added to context and made editable with `ResourceManager`, then modifications are applied with `EditFile`: -Tool Call: EditFile -Arguments: {"file_path": "main.py", "find_text": "old_function", "replace_text": "new_function"} +```text +Tool Call: ResourceManager +Arguments: {"add": ["main.py"]} Tool Call: EditFile -Arguments: {"file_path": "main.py", "after_pattern": "import statements", "content": "new_imports"} +Arguments: {"edits": [{"file_path": "main.py", "operation": "replace", "start_line": "——def old_function():", "end_line": "—— return old_value", "text": "def new_function():\n return new_value"}]} ``` +`EditFile` accepts an `edits` array containing `replace` or `delete` operations. Its line targets come from the latest `ReadFile` result. `ResourceManager` can add files as editable or read-only and remove them from context. + #### 4. Verification Phase -Changes are verified and the process continues: +Changes are verified with the available tools: -``` +```text Tool Call: GitDiff Arguments: {} -Tool Call: ListChanges -Arguments: {} +Tool Call: ReadFile +Arguments: {"read": [{"file_path": "main.py", "range_start": "@000", "range_end": "000@"}]} + +Tool Call: UndoChange +Arguments: {"change_id": "..."} ``` +`GitDiff` is available when enabled in the configuration; it is excluded by default. + #### 5. Completion Phase -The above continues over and over until: +The agent continues until the task is complete and then calls `Yield`: -``` +```text Tool Call: Yield Arguments: {} ``` +`Yield` is the registry's essential tool. When sub-agents are active, it waits for their outstanding tasks; completed summaries and errors are injected into the parent conversation before completion. + ### Agent Configuration + Agent Mode can be configured using the `--agent-config` command line argument, which accepts a JSON string for fine-grained control over tool availability and behavior. Agent Mode can also be configured directly in your configuration file. See the [Complete Configuration Example](#agent-mode-how-agent-mode-works-agent-configuration-complete-configuration-example) below for a full reference. #### Configuration Options -- **`large_file_token_threshold`**: Maximum token threshold for large file warnings (default: 32768) -- **`skip_cli_confirmations`**: YOLO mode, be brave and let the LLM cook, can also use the option `yolo` (default: False) -- **`allowed_commands`**: Array of glob patterns for commands that can be executed without prompting. Commands matching any pattern will skip the confirmation dialog. Example: `["wc -l*"]` (default: []) -- **`tools_includelist`**: Array of tool names to allow (only these tools will be available) -- **`tools_excludelist`**: Array of tool names to exclude (these tools will be disabled) -- **`tools_paths`**: Array of directories or Python files containing custom tools to load -- **`servers_includelist`**: Array of MCP server names to allow (only these servers will be available) -- **`servers_excludelist`**: Array of MCP server names to exclude (these servers will be disabled) -- **`show_lint_errors`**: When enabled, linting errors found during editing will be displayed in the tool output, allowing the LLM to see and address them (default: false) -- **`subagent_paths`**: Array of directories to search for sub-agent definition `.md` files -- **`max_sub_agents`**: Maximum number of concurrent sub-agents (default: 3) -- **`allow_nested_delegation`**: Allow sub-agents to delegate tasks to further sub-agents (default: `false`). When enabled, the `Delegate` tool is made available in sub-agent tool schemas. -- **`include_context_blocks`**: Array of context block names to include (overrides default set) -- **`exclude_context_blocks`**: Array of context block names to exclude from default set -- **`hot_reload`**: When enabled, skills configuration is hot-reloaded automatically, reflecting changes to skills without requiring a restart (default: false) -- **`command_timeout`**: Time in seconds to wait for shell commands to finish before automatic backgrounding occurs (default: None) -- **`diff_colors`**: When enabled, diff output in edit tool responses uses color-coded lines - removed lines in magenta, added lines in light green, and context lines in plain text (default: true) - -- **`orchestration`**: A nested configuration object for the Orchestrate tool's Python sandbox. - When absent or empty, the sandbox runs with default restrictions. See [Orchestration - Configuration](#agent-mode-how-agent-mode-works-agent-configuration-orchestration-configuration) below for details. +- **`large_file_token_threshold`**: Maximum token threshold for large file warnings (default: `8192`) +- **`skip_cli_confirmations`**: YOLO mode; `yolo` is accepted as an alias (default: `false`) +- **`allowed_commands`**: Array of glob patterns for commands that can be executed without prompting. Example: `["wc -l*"]` (default: `[]`) +- **`tools_includelist`**: Array of tool names to allow. When non-empty, only these tools are available; `yield` is automatically retained. +- **`tools_excludelist`**: Array of tool names to exclude +- **`tools_paths`**: Array of directories or Python files containing custom tools. `tool_paths` is accepted as an alias. +- **`servers_includelist`**: Array of MCP server names to allow. `servers_whitelist` is accepted as an alias. +- **`servers_excludelist`**: Array of MCP server names to exclude. `servers_blacklist` is accepted as an alias. +- **`show_lint_errors`**: When enabled, linting errors found during editing are displayed in tool output (default: `false`) +- **`subagent_paths`**: Array of directories to search for sub-agent definition `.md` files. `~/.cecli/subagents` and the built-in defaults directory are also scanned. +- **`max_sub_agents`**: Maximum number of active sub-agents (default: `30`; `-1` means effectively unlimited) +- **`allow_nested_delegation`**: Allow sub-agents to delegate tasks to further sub-agents (default: `false`) +- **`include_context_blocks`**: Array of context block names to include, replacing the default set +- **`exclude_context_blocks`**: Array of context block names to exclude from the selected set +- **`hot_reload`**: When enabled, skills configuration is hot-reloaded automatically (default: `false`) +- **`command_timeout`**: Seconds used when waiting for background command completion (default: `30`) +- **`diff_colors`**: When enabled, edit diffs use color-coded removed, added, and context lines (default: `true`) +- **`allow_orchestration`**: Enables the `Orchestrate` tool and its context block (default: `true`) + +- **`orchestration`**: A nested configuration object for the Orchestrate tool's Python sandbox. When absent or empty, the sandbox runs with default restrictions. See [Orchestration Configuration](#agent-mode-how-agent-mode-works-agent-configuration-orchestration-configuration) below for details. #### Orchestration Configuration @@ -216,13 +221,13 @@ agent-config: #### Essential Tools -Certain tools are always available regardless of includelist/excludelist settings: +Only `Yield` is protected as an essential registry tool. Other tools, including `ResourceManager` and `ReadFile`, can be restricted by includelist/excludelist settings. -- `ResourceManager` - Add, drop, and make files editable in the context -- `readfile` - Read file contents with virtual ID prefixes -- `yield` - Complete the task +- `ResourceManager` - Add, drop, and make files editable in context +- `ReadFile` - Read file contents with virtual content IDs +- `Yield` - Complete the task and wait for active child agents -The registry also supports **Custom Tools** that can be loaded from specified directories or files using the `tool_paths` configuration option. Custom tools must be Python files containing a `Tool` class that inherits from `BaseTool` and defines a `NORM_NAME` attribute. +The registry also supports **Custom Tools** that can be loaded from specified directories or files using the `tools_paths` configuration option. Custom tools must be Python files containing a `Tool` class that inherits from `BaseTool` and defines a `NORM_NAME` attribute. ##### Creating Custom Tools @@ -280,21 +285,36 @@ The `tools_paths` can include: Tools are loaded automatically when the registry is built and will be available alongside the built-in tools. +#### Sub-agent Behavior + +`Delegate` accepts one or more delegation objects. Each delegation includes a registered sub-agent `name`, a `prompt`, and an optional `async` flag. Asynchronous delegations run in the background; synchronous delegations wait for the sub-agent result. The system uses `Yield` to wait for outstanding child tasks when finishing the parent task. + +Sub-agent results are reported back to the parent conversation as summaries or errors. Sub-agents use `auto_reap: true` by default, so completed agents can be removed automatically after their work and descendants finish. Independent agents may be cleaned up shortly after completion, while the service also reaps completed agents when the configured limit requires space. Set `max_sub_agents` to `-1` to remove the limit on simultaneous sub agents. + +Sub-agent definition files may specify a `model` using one of these runtime-resolved values: ``, ``, ``, or ``. Nested delegation is disabled by default; enable `allow_nested_delegation` to expose `Delegate` to sub-agents and allow nested child-agent context. + #### Context Blocks -The following context blocks are available by default and can be customized using `include_context_blocks` and `exclude_context_blocks`: +The following context blocks are available and can be customized using `include_context_blocks` and `exclude_context_blocks`: + +**Included by default:** -- **`context_summary`**: Shows current context usage and token limits -- **`directory_structure`**: Displays the project's file structure -- **`git_status`**: Shows current git branch, status, and recent commits -- **`symbol_outline`**: Lists classes, functions, and methods in current context -- **`todo_list`**: Shows the current todo list managed via `UpdateTodoList` tool -- **`skills`**: Include skills content in the conversation -- **`sub_agents`**: Include registered sub-agents in the conversation context +- **`environment_info`**: Working directory, platform, date, language, and repository details +- **`todo_list`**: Current tasks managed through `UpdateTodoList` +- **`skills`**: Available skills and their configuration +- **`servers`**: Connected, filtered, and disconnected MCP servers +- **`sub_agents`**: Registered sub-agents (shown to the primary agent; nested agents require nested delegation to see child-agent context) +- **`orchestration`**: Orchestrate guidance when `allow_orchestration` is enabled -When `include_context_blocks` is specified, only the listed blocks will be included. When `exclude_context_blocks` is specified, the listed blocks will be removed from the default set. +**Available when explicitly included:** -#### Other Cecli Config Options for Agent Mode +- **`context_summary`**: Current file and context-block token usage and limits +- **`directory_structure`**: Project file structure +- **`git_status`**: Current git branch, status, and recent commits +- **`symbol_outline`**: Classes, functions, and methods in current context + + +When `include_context_blocks` is specified, it replaces the default set. `exclude_context_blocks` then removes named blocks from that set. - `use-enhanced-map` - Use enhanced repo map that takes into account import relationships between files @@ -313,47 +333,48 @@ agent: true # Agent Mode configuration agent-config: # Tool configuration - tools_includelist: ["resourcemanager", "readfile", "yield"] # Optional: Whitelist of tools - tools_excludelist: ["command", "commandinteractive"] # Optional: Blacklist of tools - tools_paths: ["./custom-tools", "~/my-tools"] # Optional: Directories or files containing custom tools - + tools_includelist: ["resourcemanager", "readfile", "yield"] + tools_excludelist: ["command"] + tools_paths: ["./custom-tools", "~/my-tools"] + # Server configuration - servers_includelist: ["local"] # Optional: Whitelist of MCP server names to allow - servers_excludelist: [] # Optional: Blacklist of MCP server names to exclude - + servers_includelist: ["local"] + servers_excludelist: [] + # Sub-agent configuration - subagent_paths: [".cecli/subagents"] # Optional: Directories to search for sub-agent definitions - max_sub_agents: 30 # Optional: Maximum concurrent sub-agents (default: 3) - allow_nested_delegation: false # Optional: Allow sub-agents to delegate further (default: false) + subagent_paths: [".cecli/subagents"] + max_sub_agents: 30 # -1 means effectively unlimited + allow_nested_delegation: false # Context blocks configuration - include_context_blocks: ["todo_list", "git_status"] # Optional: Context blocks to include - exclude_context_blocks: ["symbol_outline", "directory_structure"] # Optional: Context blocks to exclude - + include_context_blocks: ["todo_list", "git_status"] + exclude_context_blocks: ["symbol_outline", "directory_structure"] + # Performance and behavior settings - large_file_token_threshold: 32768 # Token threshold for large file warnings (default: 32768) - skip_cli_confirmations: false # YOLO mode - be brave and let the LLM cook - allowed_commands: ["wc -l*"] # Commands matching these glob patterns will not prompt for confirmation - show_lint_errors: false # When enabled, linting errors are shown in tool output (default: false) - hot_reload: false # When enabled, skills configuration is hot-reloaded automatically (default: false) - diff_colors: true # When enabled, diff output uses color-coded lines (default: true) - - # Orchestration sandbox configuration (optional) + large_file_token_threshold: 8192 + command_timeout: 30 + skip_cli_confirmations: false + allowed_commands: ["wc -l*"] + show_lint_errors: false + hot_reload: false + diff_colors: true + allow_orchestration: true + + # Orchestration sandbox configuration orchestration: - allowed_imports: [] # Optional: Module names to allow importing - allowed_builtins: [] # Optional: Builtin names to add - allow_classes: false # Optional: Allow class definitions - disable_security: false # Optional: Disable security filter (⚠ dangerous) - disable_loop_protection: false # Optional: Disable loop yield injection - - # Skills configuration (see Skills documentation for details) - skills_paths: ["~/my-skills", "./project-skills"] # Directories to search for skills - skills_includelist: ["python-refactoring", "react-components"] # Optional: Whitelist of skills to include - skills_excludelist: ["legacy-tools"] # Optional: Blacklist of skills to exclude - skills_init: ["python-refactoring"] # Optional: Skills to load and enable on startup - -# Other Agent Mode options -use-enhanced-map: true # Use enhanced repo map with import relationships + allowed_imports: [] + allowed_builtins: [] + allow_classes: false + disable_security: false + disable_loop_protection: false + + # Skills configuration + skills_paths: ["~/my-skills", "./project-skills"] + skills_includelist: ["python-refactoring", "react-components"] + skills_excludelist: ["legacy-tools"] + skills_init: ["python-refactoring"] + + ``` This configuration system allows for fine-grained control over which tools are available in Agent Mode, enabling security-conscious deployments and specialized workflows while maintaining essential functionality. diff --git a/cecli/website/docs/config/conf.md b/cecli/website/docs/config/conf.md index e254d5019a2..b7e1272784d 100644 --- a/cecli/website/docs/config/conf.md +++ b/cecli/website/docs/config/conf.md @@ -4,7 +4,7 @@ nav_order: 15 description: How to configure cecli with a YAML config file. --- -# YAML config file +# YAML Config File Most of cecli's options can be set in an `.cecli.conf.yml` file. cecli will look for a this file in these locations: diff --git a/cecli/website/docs/config/editor.md b/cecli/website/docs/config/editor.md index 0c682b876ce..37cc52b3e6f 100644 --- a/cecli/website/docs/config/editor.md +++ b/cecli/website/docs/config/editor.md @@ -4,7 +4,7 @@ nav_order: 100 description: How to configure a custom editor for cecli's /editor command --- -# Editor configuration +# Editor Configuration Cecli allows you to configure your preferred text editor for use with the `/editor` command. The editor must be capable of running in "blocking mode", meaning the command line will wait until you close the editor before proceeding. diff --git a/cecli/website/docs/config/model-configuration.md b/cecli/website/docs/config/model-configuration.md index 641d8822923..87737ca5323 100644 --- a/cecli/website/docs/config/model-configuration.md +++ b/cecli/website/docs/config/model-configuration.md @@ -4,6 +4,8 @@ nav_order: 900 description: Configure model overrides, alias-based suffixes, and structured override groups. --- +# Model Configuration + ## Model Configuration & Overrides Cecli allows you to customize and override LLM configurations to fine-tune their behavior, API parameters, and metadata. You can organize these overrides into three logical configuration groups, and apply them either as **defaults** (by model name) or via **suffixes** (e.g., `gpt-5:high`). diff --git a/cecli/website/docs/config/options.md b/cecli/website/docs/config/options.md index def01d1c0f2..8d1bfb807ef 100644 --- a/cecli/website/docs/config/options.md +++ b/cecli/website/docs/config/options.md @@ -4,7 +4,7 @@ nav_order: 10 description: Details about all of cecli's settings. --- -# Options reference +# CLI Options Reference You can use `cecli --help` to see all the available options, or review them below. diff --git a/cecli/website/docs/config/reasoning.md b/cecli/website/docs/config/reasoning.md index 60c9ec0e0f0..f4e19997dc3 100644 --- a/cecli/website/docs/config/reasoning.md +++ b/cecli/website/docs/config/reasoning.md @@ -4,6 +4,8 @@ nav_order: 110 description: How to configure reasoning model settings from secondary providers. --- +# Reasoning Models + ## Basic usage Cecli is configured to work with most popular reasoning models out of the box. You can use them like this: diff --git a/cecli/website/docs/config/skills.md b/cecli/website/docs/config/skills.md index d1c3993e760..acddc7a2e7d 100644 --- a/cecli/website/docs/config/skills.md +++ b/cecli/website/docs/config/skills.md @@ -4,7 +4,7 @@ nav_order: 35 description: Extend AI capabilities with custom instructions, reference materials, scripts, and assets through the skills system. --- -# Skills System +# Skills Agent Mode includes a powerful skills system that allows you to extend the AI's capabilities with custom instructions, reference materials, scripts, and assets. Skills are organized collections of knowledge and tools that help the AI perform specific tasks more effectively. diff --git a/cecli/website/docs/git.md b/cecli/website/docs/git.md index 5e01233b25d..2cffa9ef516 100644 --- a/cecli/website/docs/git.md +++ b/cecli/website/docs/git.md @@ -4,7 +4,7 @@ nav_order: 100 description: cecli is tightly integrated with git. --- -# Git integration +# Git Integration Cecli works best with code that is part of a git repo. cecli is tightly integrated with git, which makes it easy to: diff --git a/cecli/website/docs/index.md b/cecli/website/docs/index.md index 7da2623e1a0..ad05457d78d 100644 --- a/cecli/website/docs/index.md +++ b/cecli/website/docs/index.md @@ -26,8 +26,6 @@ cecli --model openai/gpt-5.5-terra --api-key openai= cecli --model deepseek/deepseek-v4-flash --api-key deepseek= ``` -Want more details? [Installation Guide](install.html) · [Usage Guide](usage.html) - ## More Information ### Documentation diff --git a/cecli/website/docs/languages.md b/cecli/website/docs/languages.md index 25478f895a6..f59ad05c152 100644 --- a/cecli/website/docs/languages.md +++ b/cecli/website/docs/languages.md @@ -3,7 +3,7 @@ parent: More info nav_order: 200 description: cecli supports pretty much all popular coding languages. --- -# Supported languages +# Supported Languages Cecli should work well with most popular coding languages. This is because top LLMs are fluent in most mainstream languages, and familiar with popular libraries, packages and frameworks. diff --git a/cecli/website/docs/more/edit-formats.md b/cecli/website/docs/more/edit-formats.md index 02c38d176a4..618e415bf27 100644 --- a/cecli/website/docs/more/edit-formats.md +++ b/cecli/website/docs/more/edit-formats.md @@ -4,7 +4,7 @@ nav_order: 490 description: cecli uses various "edit formats" to let LLMs edit source files. --- -# Edit formats +# Edit Formats Cecli uses various "edit formats" to let LLMs edit source files. Different models work better or worse with different edit formats. cecli is configured to use the optimal format for most popular, common models. You can always force use of a specific edit format with the `--edit-format` switch. diff --git a/cecli/website/docs/repomap.md b/cecli/website/docs/repomap.md index 60dbe6a4330..108bf9359f6 100644 --- a/cecli/website/docs/repomap.md +++ b/cecli/website/docs/repomap.md @@ -5,7 +5,7 @@ nav_order: 300 description: cecli uses a map of your git repository to provide code context to LLMs. --- -# Repository map +# Repository Map Cecli uses a **concise map of your whole git repository** that includes the most important classes and functions along with their types and call signatures. This helps cecli understand the code it's editing and how it relates to the other parts of the codebase. The repo map also helps cecli write new code that respects and utilizes existing libraries, modules and abstractions found elsewhere in the codebase. diff --git a/cecli/website/docs/troubleshooting.md b/cecli/website/docs/troubleshooting.md index 473cf1c3c46..627f9c58f7a 100644 --- a/cecli/website/docs/troubleshooting.md +++ b/cecli/website/docs/troubleshooting.md @@ -6,9 +6,25 @@ description: How to troubleshoot problems with cecli and get help. # Troubleshooting -Below are some approaches for troubleshooting problems with cecli. +Below are some approaches for troubleshooting problems with cecli: -If you need more help, please check our [GitHub issues](https://github.com/cecli-dev/cecli/issues) and file a new issue if your problem isn't discussed. Or drop into our [Discord](https://discord.gg/g4bF53fSWF) to chat with us. +- Reproduce the problem with the smallest possible command and set of files. +- Check the terminal output for the first error, rather than only the final message. +- Confirm that cecli and its dependencies are up to date, then retry if the problem may be version-related. +- Try `--verbose` or `--debug` when more diagnostic information is needed, and save the resulting logs for an issue report. +- If the problem involves a model or provider, record the model name, provider, and relevant configuration without sharing credentials. + +## Create logs for an issue report + +When asking for help in [Discord](https://discord.gg/g4bF53fSWF) or opening a [GitHub issue](https://github.com/cecli-dev/cecli/issues), include the relevant command, cecli version, operating system, model/provider, and a log captured while reproducing the problem. Do not include API keys, tokens, passwords, or other sensitive information. + +Use `--verbose` and `--debug` for additional diagnostic output: + +```console +cecli --verbose --debug +``` + +If the problem involves an LLM request, `--debug` may also create request logs under `.cecli/logs/`. Review and redact those files before sharing them, since request logs can contain prompts or other private project content. Attach the redacted log files to your GitHub issue or upload them in Discord, and briefly explain what you expected to happen and what happened instead. > **Tip:** > Use `/help ` to [ask for help about using cecli](troubleshooting/support.html), customizing settings, using LLMs, etc. diff --git a/cecli/website/docs/usage.md b/cecli/website/docs/usage.md index e60cebfbedd..d4229857023 100644 --- a/cecli/website/docs/usage.md +++ b/cecli/website/docs/usage.md @@ -6,7 +6,19 @@ description: How to use cecli to pair program with AI and edit code in your loca # Usage -Run `cecli` with the source code files you want to edit. These files will be "added to the chat session", so that cecli can see their contents and edit them for you. They can be existing files or the name of files you want cecli to create for you. +Cecli is a general terminal agent that can be used for coding, analysis, research and other workflows that can be expressed programmatically through scripting, file modification, and CLI commands. + +## Adding files + +To edit files, you need to "add them to the chat". You can use the in-chat `/add` command to add files. They can be existing files or the name of files you want cecli to create for you. With no arguments, `/add` will open a fuzzy finder that lets you select files from your repository. This feature is enabled if you have `fzf` installed. Otherwise, `/add` requires file paths as arguments. + +Only add the files that need to be edited for your task. Don't add a bunch of extra files. If you add too many files, the LLM can get overwhelmed and confused (and it costs more tokens). cecli will automatically pull in content from related files so that it can [understand the rest of your code base](repomap.html). + +You can use cecli without adding any files, and it will try to figure out which files need to be edited based on your requests. + +### Adding files (CLI) + +You can also add files directly from the CLI with: ``` cecli ... @@ -27,17 +39,6 @@ Environment .git (258 files) • repo-map disabled ... ``` -> **Tip:** -> Use `/help ` to [ask for help about using cecli](troubleshooting/support.html), customizing settings, troubleshooting, using LLMs, etc. - -## Adding files - -To edit files, you need to "add them to the chat". Do this by naming them on the cecli command line. Or, you can use the in-chat `/add` command to add files. With no arguments, `/add` will open a fuzzy finder that lets you select files from your repository. This feature is enabled if you have `fzf` installed. Otherwise, `/add` requires file paths as arguments. - -Only add the files that need to be edited for your task. Don't add a bunch of extra files. If you add too many files, the LLM can get overwhelmed and confused (and it costs more tokens). cecli will automatically pull in content from related files so that it can [understand the rest of your code base](repomap.html). - -You can use cecli without adding any files, and it will try to figure out which files need to be edited based on your requests. - > **Tip:** You'll get the best results if you think about which files need to be edited. Add **just** those files to the chat. cecli will include relevant context from the rest of your repo. ## Read-only files @@ -68,3 +69,6 @@ Or you can run `cecli --model XXX` to launch cecli with another model. During yo Ask cecli to make changes to your code. It will show you some diffs of the changes it is making to complete you request. [cecli will git commit all of its changes](git.html), so they are easy to track and undo. You can always use the `/undo` command to undo AI changes that you don't like. + +> **Tip:** +> Use `/help ` to [ask for help about using cecli](troubleshooting/support.html), customizing settings, troubleshooting, using LLMs, etc. \ No newline at end of file diff --git a/cecli/website/docs/usage/copypaste.md b/cecli/website/docs/usage/copypaste.md index 69e432f0b54..da53a312603 100644 --- a/cecli/website/docs/usage/copypaste.md +++ b/cecli/website/docs/usage/copypaste.md @@ -1,12 +1,11 @@ --- -title: Copy/paste with web chat -#highlight_image: /assets/browser.jpg +title: Copy/Paste Mode parent: Usage nav_order: 850 description: cecli works with LLM web chat UIs --- -## Working with an LLM web chat +## Copy/Paste Mode [Cecli can connect to most LLMs via API](../llms.html) and works best that way. But there are times when you may want to work with an LLM via its web chat interface: diff --git a/cecli/website/docs/usage/images-urls.md b/cecli/website/docs/usage/images-urls.md index 892407260d8..7e5ccc0f73b 100644 --- a/cecli/website/docs/usage/images-urls.md +++ b/cecli/website/docs/usage/images-urls.md @@ -4,7 +4,7 @@ nav_order: 700 description: Add images and web pages to the cecli coding chat. --- -# Images & web pages +# Images & Web Pages You can add images and URLs to the cecli chat. diff --git a/cecli/website/docs/usage/lint-test.md b/cecli/website/docs/usage/lint-test.md index e2bbdaf5104..04ef66c7a84 100644 --- a/cecli/website/docs/usage/lint-test.md +++ b/cecli/website/docs/usage/lint-test.md @@ -4,7 +4,7 @@ nav_order: 900 description: Automatically fix linting and testing errors. --- -# Linting and testing +# Linting and Testing Cecli can automatically lint and test your code every time it makes changes. This helps identify and repair any problems introduced by the AI edits. diff --git a/cecli/website/docs/usage/modes.md b/cecli/website/docs/usage/modes.md index 4d365e09a11..d51aeafe109 100644 --- a/cecli/website/docs/usage/modes.md +++ b/cecli/website/docs/usage/modes.md @@ -4,7 +4,7 @@ nav_order: 60 description: Using the code, architect, ask, help and agent modes. --- -# Chat modes +# Chat Modes Cecli has a few different chat modes: diff --git a/cecli/website/docs/usage/voice.md b/cecli/website/docs/usage/voice.md index 9410037b4f4..d46bad74f87 100644 --- a/cecli/website/docs/usage/voice.md +++ b/cecli/website/docs/usage/voice.md @@ -4,7 +4,7 @@ nav_order: 100 description: Speak with cecli about your code! --- -# Voice-to-code with cecli +# Voice Mode Speak with cecli about your code! Request new features, test cases or bug fixes using your voice and let cecli do the work of editing the files in your local git repo. As with all of cecli's capabilities, you can use voice-to-code with an existing repo or to start a new project. diff --git a/cecli/website/index.html b/cecli/website/index.html index e0485a82225..70e1d01b6f4 100644 --- a/cecli/website/index.html +++ b/cecli/website/index.html @@ -21,10 +21,7 @@