Agent
The agent is the core of Codality. It reads your code, makes changes, runs tests, and commits.
How it works
When you start the agent on a ticket, it:
- Creates a git worktree on a dedicated branch for the ticket
- Starts a Docker container (or falls back to host execution)
- Receives a system prompt composed of: base identity, the ticket kind's methodology, the priority's approach instructions, available tools, and git workflow rules
- Receives the ticket description plus any existing comments as the initial user message
- Enters an agentic loop: reasons about what to do, calls tools, processes results, and repeats until the work is complete
- Transitions the ticket to in_review when done
Each agent session has a 10-minute timeout. The session uses the model configured in settings (default: gpt-5.2).
Sandbox
The agent runs shell commands inside an isolated Docker container. Each session gets its own container with:
- 4 GB RAM, 2 CPUs
- The project worktree mounted at
/workspace - A shared tools directory at
/tools(persists across sessions) - Network access (
--network host) - Security:
--security-opt no-new-privileges
The default image is ubuntu:24.04. Projects can configure a custom Docker image (e.g., node:20, python:3.12) in project settings.
If Docker is not available, the agent runs commands directly on the host. See Docker Sandbox for full details.
Tools
The agent has access to 16 tools:
| Tool | Description |
|---|---|
bash |
Run shell commands inside the Docker sandbox (builds, tests, git operations). 60-second timeout. |
read_file |
Read file contents (max 50 KB) |
write_file |
Create or overwrite a file (auto-creates parent directories) |
edit_file |
Search-and-replace within a file (the search text must be unique) |
grep |
Search files with regex patterns (returns up to 50 matches) |
list_directory |
List directory contents with file sizes |
get_ticket |
Look up another ticket by number |
search_tickets |
Search for related tickets by text |
memory |
Query project memory: past tickets, plans, agent sessions, reviews |
browser_navigate |
Open a URL in a headless browser (returns automatic screenshot) |
browser_screenshot |
Take a screenshot of the current page |
browser_eval_js |
Execute JavaScript in the browser |
browser_wait |
Wait for a duration (max 5 seconds) |
browser_resize |
Resize the browser viewport (auto-screenshots after resize) |
web_search |
Search the web for documentation and solutions (via Tavily API) |
web_extract |
Extract full content from a URL (via Tavily API) |
Memory
The memory tool gives the agent read-only access to project history. It can query:
- Project overview and recent tickets
- Individual ticket details and timelines
- Past agent sessions and their outcomes
- Plans and plan details
- Code reviews
- Agent statistics
The agent typically uses this at the start of a session to orient itself and understand context from previous work.
Context management
Long agent sessions can exceed the model's context window. Codality uses a 3-tier gradient memory system to handle this:
| Tier | Turns | Treatment |
|---|---|---|
| Recent | Last 4 turns | Kept verbatim |
| Middle | Older turns | Tool call arguments and responses truncated, text preserved |
| Ancient | Oldest turns | Compacted into an opaque token via OpenAI's /responses/compact API |
The system budgets 80% of the model's context window. Before every LLM call, a callback estimates token count and progressively applies compaction until the request fits. This allows sessions to run for millions of tokens without losing track of what they've done.
Git workflow
Each ticket gets a dedicated branch and worktree. The branch is named agent/ticket-{N}-{title-slug}.
The agent:
- Makes atomic commits as it completes logical units of work
- Writes descriptive commit messages prefixed with the ticket number (e.g.,
[#3] Add user authentication endpoint) - Runs tests before the final commit
- Never commits generated files or build artifacts
The worktree is rebased onto the latest default branch at the start of each session. On merge, the branch is merged with --no-ff (or cherry-picked if histories are unrelated), then pushed to origin.
Git identity & SSH keys
The agent commits and pushes using the ticket creator's git identity:
- Name and email: Configured per user in Profile → Git Identity. Falls back to the user's Codality name and email.
- SSH key: Auto-generated ED25519 keypair per user on first agent run. Stored at
{worktree_base}/../ssh/{user_id}/id_ed25519.
View and copy your SSH public key in Profile → SSH Key. Add it to your Git hosting provider as a deploy key for push access.
Inside the Docker sandbox, the SSH key is mounted read-only and GIT_SSH_COMMAND is configured with StrictHostKeyChecking=accept-new.
Real-time streaming
The web UI streams agent activity in real time via Server-Sent Events (SSE). You see:
- Thinking — The agent's reasoning process (displayed inline with a brain icon)
- Tool calls — Commands executed, files read, searches performed
- Text responses — The agent explaining what it's doing
- Commits — Git commits as they happen
Agent thinking is always displayed inline and visible — never hidden or collapsed.
Sending messages during execution
You can send messages to a running agent by posting comments on the ticket. Messages are buffered and injected into the next LLM call as [USER INTERJECTION] content. The agent reads and responds to them naturally.
This is useful for course corrections: "skip the tests for now" or "the config file is at /etc/app.conf, not where you're looking."
Stopping the agent
Click Stop to interrupt the agent. It stops after completing the current tool call. Any commits already made are preserved in the worktree.
Re-running the agent
You can run the agent multiple times on the same ticket. Each run continues from where the worktree was left — previous commits are preserved. The worktree is rebased onto the latest default branch at the start of each session.
Add comments before re-running to give the agent additional instructions.
Trigger context
When the agent is triggered by external events (CI failure, PR comment, review feedback), it receives a trigger context prepended to its initial message. This context includes the specific failure details, comment text, or review feedback that prompted the run.
See CI Feedback Loop for details on automated triggers.
Cost tracking
Each agent session tracks token usage (input and output) and calculates cost based on the model's pricing. View session costs in the ticket detail activity feed. Codality supports pricing for all GPT-5.x, GPT-4.1, GPT-4o, and o-series models.
Work queue integration
Tickets that belong to a work queue execute sequentially. When one ticket's agent completes and the ticket reaches done, the next ticket in the queue starts automatically. If the agent fails, the queue pauses.
Work queue tickets cannot be started individually — they must go through the queue's sequential execution.