Agent Overview

What Is the Agent

When you type a message in the Creor chat panel, you are talking to an AI agent -- not just a language model. The agent wraps the underlying LLM with a tool-use loop that can read your codebase, edit files, run shell commands, search the web, and coordinate parallel sub-tasks. Each response is the result of one or more iterations through this loop until the agent decides it has fully addressed your request.

Unlike a simple chat completion, the agent maintains a persistent session with your project context. It knows your file structure, open editors, recent changes, and any project-level instructions you have defined in CREOR.md or .creor/ rules.

Message Flow

Every interaction follows a loop. When you send a message, the agent reasons about the task, decides which tools to call, executes them, observes the results, and repeats until the task is complete.

User message
  -> Agent reasoning (LLM decides next action)
    -> Tool selection (read, edit, bash, grep, etc.)
      -> Tool execution (agent runs the tool)
        -> Result observation (agent reads tool output)
          -> Continue loop or return final response

A single user message can trigger dozens of tool calls. For example, asking the agent to refactor a function might involve reading the file, finding all references with grep, editing multiple files, and running tests to verify the change.

Step-by-Step Breakdown

• You send a message in the chat panel or via the CLI.
• The system prompt is assembled: project instructions, active rules, session history, and tool definitions.
• The LLM produces a response that may include one or more tool calls.
• Each tool call is checked against the permission system (allow, ask, or deny).
• Approved tool calls are executed and their results are fed back to the LLM.
• The LLM decides whether to make more tool calls or return a final text response.
• The final response is displayed in the chat panel alongside any tool call cards.

Agent Types

Creor ships with several agent configurations, each tailored for a different workflow. The default is the Build agent, which has full access to all tools.

Tool Selection

The agent does not randomly pick tools. The LLM receives a list of all available tools with their descriptions and parameter schemas. Based on your message and the current session context, it decides which tool (or tools) to invoke.

Selection Heuristics

• If the task involves understanding code, the agent starts with read, glob, and grep to explore the codebase.
• For code changes, it uses edit (exact string replacement) or write (new file creation) after reading the target file.
• Shell commands (bash) are used for running tests, installing dependencies, git operations, and build commands.
• Web tools (websearch, webfetch) are invoked when the agent needs external documentation or API references.
• Task and plan tools are used for multi-step workflows that benefit from structured execution.

The agent can call multiple tools in a single turn. When tool calls are independent of each other, they are executed in parallel for faster results.

Error Handling & Retries

When a tool call fails, the agent does not give up. It reads the error output and adapts its approach. This is one of the key advantages of an agentic workflow over a simple code generation model.

Common Recovery Patterns

• Edit failure (string not found): The agent re-reads the file to get the current content and retries with the correct match string.
• Test failure: The agent reads the test output, identifies the failing assertion, and adjusts the code.
• Build error: The agent reads compiler output, locates the error in the source file, and fixes type mismatches or syntax issues.
• Permission denied: The agent prompts you for approval or suggests an alternative approach that does not require elevated access.
• Timeout: Long-running commands are retried with adjusted parameters or broken into smaller steps.

Context Window

The agent operates within the context window of the underlying LLM. As a conversation grows, older messages and tool results may be compacted to stay within limits. Creor handles this automatically through session compaction, which summarizes earlier turns while preserving recent context.

• Recent messages and tool results are kept in full detail.
• Older turns are summarized to preserve intent while reducing token count.
• System instructions (CREOR.md, rules) are always included at full fidelity.
• Large tool outputs (e.g., reading a big file) are truncated with a note to the agent about what was cut.

Next Steps