cecli-dev 1.2.1rc1

cecli is yet another cli agent crafted for extensibility and customization. For folks who like seeing under the hood, welcome to the fold. Made for nerds, geeks, and the extremely curious.

Links

Documentation Discord Chat Issue Queue

Installation Instructions

All installation methods export a cecli command that can start the application. This project can be installed using several methods:

Linux & Mac

Use curl to download the script and execute it with sh:

curl -LsSf https://cecli.dev/install.sh | sh

If your system doesn't have curl, you can use wget:

wget -qO- https://cecli.dev/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://cecli.dev/install.ps1 | iex"

Package Installation

uv pip install --native-tls cecli-dev

or

pip install cecli-dev

Tool Installation

uv tool install --native-tls --python python3.12 cecli-dev

Use the tool installation so cecli doesn't interfere with your development environment

Prompt Queue Management

The cecli CLI includes a prompt queueing feature (CLI-33) that allows users to manage multiple prompts in a first-in-first-out (FIFO) in-memory queue. The queue is tied to the user's CLI session and does not persist across restarts.

Queue Lifecycle

1. Enqueue: /queue <prompt> adds a prompt to the queue.
2. List: /list-queue displays all queued prompts with index numbers and timestamps.
3. Remove: /remove-queue [index|*] removes a specific item by index, clears the entire queue with *, or provides interactive selection when called with no arguments.
4. Auto-Process: After the current command completes and the system is idle (cmd_running_event is set), queued prompts are processed sequentially in FIFO order.

Commands

• /queue <prompt text> — Adds a prompt to the queue. Confirms with the queue position.
• /list-queue — Displays a numbered list of queued prompts ([index] text (timestamp)). Shows "Queue is empty" when appropriate.
• /remove-queue <index> — Removes the prompt at the given 0-based index.
• /remove-queue * — Clears the entire queue.
• /remove-queue (no args) — Enters interactive selection mode.

Queue Limits

• Max Queue Size: 100 items (hard limit). New prompts are rejected with a warning when the queue is full.
• Max Prompt Length: 10,000 characters per queued item. Prompts exceeding this limit are rejected.
• In-Memory Only: The queue is stored on the Commands instance (cecli/commands/core.py) and is lost when the CLI session restarts.

Queue Processing Integration

Queue processing is triggered in the finally block of Commands.execute() after cmd_running_event.set(). Management commands (queue, list-queue, remove-queue) are excluded from triggering auto-processing to prevent unexpected behavior. A _processing_queue boolean flag prevents infinite recursion if a queued prompt itself queues another item.

Example Workflow

# Queue multiple prompts
/queue "refactor database layer"
/queue "add unit tests for user service"

# View queued prompts
/list-queue
# Output: [1] refactor database layer (2026-08-01 10:30:00)
#         [2] add unit tests for user service (2026-08-01 10:30:05)

# Remove a specific queued prompt
/remove-queue 1

# Clear the entire queue
/remove-queue *

# Queued prompts process automatically after the current command completes

Management Command Guard

The management commands (/queue, /list-queue, /remove-queue) must not trigger auto-processing of queued items. Their execution is isolated so that the current prompt continues uninterrupted. When any of these commands is entered while another prompt is being processed, they execute immediately without clearing cmd_running_event or steering the ongoing command.

Thread Safety

The queue uses a single-threaded async event loop. List operations on prompt_queue are naturally safe within the async loop. An asyncio.Lock (_queue_lock) protects all read and write operations to ensure atomic updates.

The prompt queueing feature enhances the user experience by providing robust prompt management capabilities, increasing efficiency, and preventing interruptions during ongoing tasks.

The documentation above contains the full set of allowed configuration options but I highly recommend using an .cecli.conf.yml file. A good place to get started is:

model: <model of your choice>
agent: true
auto-commits: true
auto-save: true
cache-prompts: true
check-update: true
enable-context-compaction: true
context-compaction-max-tokens: 0.8
show-model-warnings: true

agent-config:
  large_file_token_threshold: 8192
  skip_cli_confirmations: false

mcp-servers:
  mcpServers:
    context7:
      transport: http
      url: https://mcp.context7.com/mcp

Use the adjacent .cecli.env file to store model api keys as environment variables, e.g:

ANTHROPIC_API_KEY="..."
GEMINI_API_KEY="..."
OPENAI_API_KEY="..."
OPENROUTER_API_KEY="..."
DEEPSEEK_API_KEY="..."

Run Program

If you are in the directory with your .cecli.conf.yml file, then simply running cecli will start the agent with your configuration. For best results, since terminal emulators can be finicky, we highly suggest running:

cecli --terminal-setup

On first run to configure keybindings for the program (notably shift+enter). Support for terminals is ongoing so feel free to make a github issue or chat in the discord for us to figure out what's needed to support automatically setting up a given terminal.

If you want additional sandboxing, we publish a docker container that can be ran as follows:

docker pull dustinwashington/cecli
docker run \
  -it \
  --user $(id -u):$(id -g) \
  --volume $(pwd):/app \
  --volume $(pwd)/.cecli.conf.yml:/.cecli.conf.yml \
  --volume $(pwd)/.cecli.env:/.cecli.env \
  dustinwashington/cecli \
  --config /.cecli.conf.yml
  --env-file /.cecli.env

This command will make sure all commands ran by the coding agent happen in context of the docker container to protect the host file system from any infamous agentic mishap

Documentation/Other Notes:

• Agent Mode

• MCP Configuration

• TUI Configuration

• Skills

• Subagents

• Persistent Memory

• Session Management

• Hooks

• Agent Client Protocol (ACP)

• Workspaces

• Custom Commands

• Custom System Prompts

• Custom Tools

• Advanced Model Configuration

• Additional Documentation

• Agent Mode

• MCP Configuration

• TUI Configuration

• Skills

• Subagents

• Session Management

• Hooks

• Workspaces

• Custom Commands

• Custom System Prompts

• Custom Tools

• Advanced Model Configuration

• Additional Documentation

Project Roadmap/Goals

The current priorities are to improve core capabilities and user experience of the cecli project

1. Base Asynchronicity (cecli coroutine-experiment branch)

• Refactor codebase to have the main loop run asynchronously
• Update test harness to work with new asynchronous methods

2. Repo Map Accuracy - Discussion

• Bias page ranking toward active/editable files in repo map parsing
• Include import information in repo map for richer context
• Handle non-unique symbols that break down in large codebases

3. Context Discovery - Discussion

• Develop AST-based search capabilities
• Enhance file search with ripgrep integration
• Implement RAG (Retrieval-Augmented Generation) for better code retrieval
• Build an explicit workflow and local tooling for internal discovery mechanisms

4. Context Delivery - Discussion

• Use workflow for internal discovery to better target file snippets needed for specific tasks (ExploreCode and ReadRange)
• Add support for partial files and code snippets in model completion messages
• Update message request structure for optimal caching

5. TUI Experience - Discussion

• Add a full TUI (probably using textual) to have a visual interface competitive with the other coding agent terminal programs
• Re-integrate pretty output formatting
• Implement a response area, a prompt area with current auto completion capabilities, and a helper area for managing utility commands

6. Agent Mode - Discussion

• Renaming "navigator mode" to "agent mode" for simplicity
• Add an explicit "finished" internal tool
• Add a configuration json setting for agent mode to specify allowed local tools to use, tool call limits, etc.
• Add a RAG tool for the model to ask questions about the codebase
• Make the system prompts more aggressive about removing unneeded files/content from the context
• Add a plugin-like system for allowing agent mode to use user-defined tools in simple python files
• Add a dynamic tool discovery tool to allow the system to have only the tools it needs in context

7. Sub Agents

• Add /invoke-agent command to manually branch a sub agent and return a summary to the main context
• Add an instance-able view of the conversation system so sub agents get their own context and workspaces
• Modify coder classes to have discrete identifiers for themselves/management utilities for them to have their own slices of the world
• Refactor global files like todo lists to live inside instance folders to avoid state conflicts
• Add a Delegate tool that launches a sub agent as a background command that the parent model waits for to finish
• Add visibility into active sub agent calls in TUI

8. Hooks

• Add hooks base class for user defined python hooks with an execute method with type and priority settings
• Add hook manager that can accept user defined files and command line commands
• Integrate hook manager with coder classes with hooks for start, end, on_message, end_message, pre_tool, and post_tool

9. Efficient File Editing

• Explore use of hashline file representation for more targeted file editing
• Assuming viability, update SEARCH part of SEARCH/REPLACE with hashline identification (Done with new edit format)
• Update agent mode edit tools to work with hashline identification
• Update internal file diff representation to support hashline propagation

10. Dynamic Context Management

• Update compaction to use observational memory sub agent calls to generate decision records that are used as the compaction basis
• Persist decision records to disk for sessions with some settings for managing lifetimes of such persistence
• Integrate RLM to extract information from decision records on disk and other definable notes
• Add a "describe" tool that launches a sub agent workflow that populates an RLM call's context with:
  • Current Conversation History
  • Past Decision Records
  • Repo Map Found Files

11. Quality of Life

• Add hot keys support for running repeatable commands like switching between preferred models
• Unified error message logging inside of .cecli directory

All Contributors (Both Cecli and Aider main)

The current priorities are to improve core capabilities and user experience of the cecli project

1. Base Asynchronicity (cecli coroutine-experiment branch)

• Refactor codebase to have the main loop run asynchronously
• Update test harness to work with new asynchronous methods

2. Repo Map Accuracy - Discussion

• Bias page ranking toward active/editable files in repo map parsing
• Include import information in repo map for richer context
• Handle non-unique symbols that break down in large codebases

3. Context Discovery - Discussion - Done with Cymbal Library

• Develop AST-based search capabilities
• Enhance file search with ripgrep integration
• Implement RAG (Retrieval-Augmented Generation) for better code retrieval
• Build an explicit workflow and local tooling for internal discovery mechanisms

4. Context Delivery - Discussion

• Use workflow for internal discovery to better target file snippets needed for specific tasks (ExploreCode and ReadRange)
• Add support for partial files and code snippets in model completion messages
• Update message request structure for optimal caching

5. TUI Experience - Discussion

• Add a full TUI (probably using textual) to have a visual interface competitive with the other coding agent terminal programs
• Re-integrate pretty output formatting
• Implement a response area, a prompt area with current auto completion capabilities, and a helper area for managing utility commands

6. Agent Mode - Discussion

• Renaming "navigator mode" to "agent mode" for simplicity
• Add an explicit "finished" internal tool
• Add a configuration json setting for agent mode to specify allowed local tools to use, tool call limits, etc.
• Add a RAG tool for the model to ask questions about the codebase
• Make the system prompts more aggressive about removing unneeded files/content from the context
• Add a plugin-like system for allowing agent mode to use user-defined tools in simple python files
• Add a dynamic tool discovery tool to allow the system to have only the tools it needs in context

7. Sub Agents

• Add /invoke-agent command to manually branch a sub agent and return a summary to the main context
• Add an instance-able view of the conversation system so sub agents get their own context and workspaces
• Modify coder classes to have discrete identifiers for themselves/management utilities for them to have their own slices of the world
• Refactor global files like todo lists to live inside instance folders to avoid state conflicts
• Add a Delegate tool that launches a sub agent as a background command that the parent model waits for to finish
• Add visibility into active sub agent calls in TUI

8. Hooks

• Add hooks base class for user defined python hooks with an execute method with type and priority settings
• Add hook manager that can accept user defined files and command line commands
• Integrate hook manager with coder classes with hooks for start, end, on_message, end_message, pre_tool, and post_tool

9. Efficient File Editing

• Explore use of hashline file representation for more targeted file editing
• Assuming viability, update SEARCH part of SEARCH/REPLACE with hashline identification (Done with new edit format)
• Update agent mode edit tools to work with hashline identification
• Update internal file diff representation to support hashline propagation

10. Dynamic Context Management (Accomplished with subagents, orchestrate, and the facts db)

• Update compaction to use observational memory sub agent calls to generate decision records that are used as the compaction basis
• Persist decision records to disk for sessions with some settings for managing lifetimes of such persistence
• Integrate RLM-like facility to extract information from decision records on disk and other definable notes
• Add a "describe" tool that launches a sub agent workflow that populates an RLM call's context with:
  • Current Conversation History
  • Past Decision Records
  • Repo Map Found Files

11. Quality of Life

• Add hot keys support for running repeatable commands like switching between preferred models
• Unified error message logging inside of .cecli directory

All Contributors (Both Cecli and Aider main)