Usage Guides
Chat Modes

Chat Modes

Cecli has a few different chat modes:

code - cecli will make changes to your code to satisfy your requests.
ask - cecli will discuss your code and answer questions about it, but never make changes.
architect - Like code mode, cecli will change your files. An architect model will propose changes and an editor model will translate that proposal into specific file edits.
help - cecli will answer questions about cecli: usage, configuration, troubleshooting, etc.
agent - cecli will autonomously explore and modify your codebase using local tools, discovering and managing the relevant files itself.

By default, cecli starts in “code” mode. As you are talking, you can send individual messages in a specific mode using /code, /architect, /ask, /help, and /agent commands: Using these /-commands applies just to that particular message. Your next message will go back to the active mode (usually “code” mode by default).

You can switch the active mode in a sticky way with the /chat-mode <mode> command:

/chat-mode code
/chat-mode architect
/chat-mode ask
/chat-mode help

Note: agent mode is not a /chat-mode value — it is an operational mode you enter with /agent (or launch with --agent). See Agent mode below.

Or you can switch between coding modes using these commands without arguments:

/code
/architect
/ask
/agent

Or you can launch cecli in one of the modes with the --chat-mode <mode> switch. There is also a special shortcut --architect to launch in --chat-mode architect, and --agent to launch directly in agent mode.

The cecli prompt will indicate the active mode:

> This is code mode.
ask> This is ask mode.
architect> This is architect mode.
agent> This is agent mode.

Agent mode

Agent mode is cecli’s autonomous, tool-based operational mode. Instead of relying on traditional edit formats, the LLM works through a continuous loop of tool calls — discovering relevant files, analyzing them, making edits, and processing the results — until the task is complete or the iteration limit is reached.

You can activate agent mode in several ways:

In the chat with /agent. This switches to agent mode temporarily to autonomously discover and manage relevant files, then returns to your original mode. For example: /agent Fix this bug or /agent Add a new feature.
On the command line with --agent (cecli ... --agent).
In your configuration files with agent: true.

What agent mode provides

Autonomous file management: cecli discovers and manages relevant files itself, rather than relying only on the files you explicitly add.
Enhanced context management: entering agent mode enables context management for large files, and you can tune it with /context-management and /context-blocks.
Skills: loading, including, excluding, and removing skills is only available in agent mode (/load-skill, /include-skill, /exclude-skill, /remove-skill).
Sub-agents: delegate sub-tasks to specialized sub-agents for parallel or focused work.
Dedicated agent model: choose a separate model for agent mode with --agent-model or /agent-model.

Agent mode works well for open-ended requests such as “fix this bug” or “add a new feature”, where the relevant files aren’t obvious up front. See Agent Mode for full configuration details, including the tool registry, context management, and orchestration settings.

Ask/code workflow

A recommended workflow is to bounce back and forth between /ask and /code modes.

Use ask mode to discuss what you want to do, get suggestions or options from cecli and provide feedback on the approach. Once cecli understands the mission, switch to code mode to have it start editing your files. All the conversation and decision making from ask mode will help ensure that the correct code changes are performed.

You can be very terse when you finally switch from ask to code mode. Saying something as simple as “go ahead” in code mode will have cecli execute on the plan you’ve been discussing.

Here’s an example with two ask mode messages to agree on the plan, followed by two terse code mode messages to edit the code.

─────────────────────────────────────────────────────────────────────────────────────
cecli v1.0.0
Model: gemini/gemini-2.5-pro-exp-03-25 with diff-fenced edit format

> /ask What's the best thing to print if we're making a quick little demo program?

It sounds like you'd like to write a "Hello, world!" program. That's a very
popular phrase to use for small demo programs.

> /ask Yes, that's the idea. What are some more creative options?

1. "Greetings, Earthlings!"
2. "Beep boop, I am a computer!"
3. "To code, or not to code, that is the question."
4. "I think, therefore I print."
5. "01001000 01101001!" (Binary for "Hi!")

> do 4

hello.py
>>>>>>> SEARCH
=======
def main():
    print("I think, therefore I print.")
<<<<<<< REPLACE

> ALL CAPS!

hello.py
>>>>>>> SEARCH
    print("I think, therefore I print.")
=======
    print("I THINK, THEREFORE I PRINT!")
<<<<<<< REPLACE

You can think of this ask/code workflow as a more fluid version of architect mode, but working just with one model the whole time.

Architect mode and the editor model

When you are in architect mode, cecli sends your requests to two models:

First, it sends your request to the main model which will act as an architect
to propose how to solve your coding request. The main model is configured with /model or --model.
cecli then sends another request to an “editor model”,
asking it to turn the architect’s proposal into specific file editing instructions. cecli has built in defaults to select an editor model based on your main model. Or, you can choose a specific editor model with --editor-model <model>.

Certain LLMs aren’t able to propose coding solutions and specify detailed file edits all in one go. For these models, architect mode can produce better results than code mode by pairing them with an editor model that is responsible for generating the file editing instructions. But this uses two LLM requests, which can take longer and increase costs.

Architect mode is especially useful with OpenAI’s o1 models, which are strong at reasoning but less capable at editing files. Pairing an o1 architect with an editor model like GPT-4o or Sonnet will give the best results.

But architect mode can also be helpful when you use the same model as both the architect and the editor. Allowing the model two requests to solve the problem and edit the files can sometimes provide better results.

The editor model uses one of cecli’s edit formats to let the LLM edit source files. cecli will pick a suitable edit format by default, but you can customize it with --editor-edit-format <format>. The “editor-diff” and “editor-whole” edit formats are the recommended edit formats when using architect mode. See this article on cecli’s architect/editor mode for more details.

Examples

cecli v1.0.0
Models: claude-3-5-sonnet-20240620 with diff edit format
Git repo: .git with 298 files
Repo-map: using 1024 tokens
Use /help to see in-chat commands, run with --help to see cmd line args

/ask What is this repo?

This is collection of python functions that compute various math functions.

/help How do I use cecli with ollama?

Run cecli --model ollama/<ollama-model>. See these docs for more info: https://cecli.dev/docs/llms/ollama/

/code Add a function to calculate the factorial of a number

Certainly! I’ll add a function to calculate the factorial of a number. Here’s the change:

def factorial(n):
    if n == 0 or n == 1:
        return 1
    else:
        return n * factorial(n - 1)

# Example usage
print(factorial(5))  # Output: 120

This function uses recursion to calculate the factorial. It’s been added to your code.

/architect Can we make this simpler?

Yes, you could replace the factorial() function with a call to the math.factorial() builtin. This way you don’t have to maintain a custom factorial implementation, and the builtin function is well optimized.

<<<<<<< SEARCH
def factorial(n):
    if n == 0 or n == 1:
        return 1
    else:
        return n * factorial(n - 1)
=======
from math import factorial
>>>>>>> REPLACE