What is CODA?

CODA is Globant's AI coding agent, designed to help you across the entire software development lifecycle (SDLC). You describe what you want to accomplish in plain language — CODA reads your codebase, figures out what needs to change, and gets it done, while you stay in control of every step.

What you can do with CODA

Explore an unfamiliar codebase — ask CODA to explain how authentication works, trace where a bug might be coming from, or map out the dependencies of a module before you touch anything.

Make changes with a safety net — CODA snapshots your files before every edit (checkpoints). If something goes wrong, you can roll back to any previous state with a single command.

Automate repetitive work — run CODA headlessly in scripts and CI pipelines. Feed it a prompt, let it work, and check the result — no terminal UI needed.

Extend it for your team — connect MCP servers, write custom skills, and create shared AGENTS.md files so every developer on the project works with the same conventions baked in.

How a session looks

Three ways to run it

Interactive (TUI) — a full-screen terminal UI. Type prompts, review tool output, approve commands, and navigate your session history in real time. This is how you'll use CODA day-to-day.

Headless (Batch) — a single command, no UI. Give CODA a prompt from the shell, it runs, and exits. Use this in scripts, CI pipelines, and automation.

Editor (ACP) — native third-party integrations via the Agent Client Protocol (ACP). This lets you use CODA inside editors like Zed and JetBrains IDEs. See Use CODA in Your Editor (ACP).

All three share the same agent and configuration.

Start here

1. Installation — get coda running on your machine.
2. Quick Start — open CODA in a real project and run your first prompt.
3. Configuration — connect your provider and tune settings.

Installation

Requirements

• Git 2.5.0 or newer — CODA uses Git under the hood for checkpoints. Run git --version to check.
• A supported terminal — any modern terminal on macOS, Linux, or Windows works.
• Provider credentials — you'll connect an AI provider on first launch: sign in to Glob.AI with your Globant account (OAuth, recommended) or an API key, or configure a custom OpenAI-compatible provider.

Install CODA

The recommended way to install CODA is the install script — it has no dependencies (it just runs the commands below), so everyone can use it.

macOS & Linux

curl -fsSL 'https://docs.globant.ai/en/filedownload?4622,12' | bash

Windows (PowerShell 7) — restart your terminal after installing

irm 'https://docs.globant.ai/en/filedownload?5346,6' | iex

Alternatively, you can install via npm. This route requires Node.js (which includes npm) — a current LTS release is recommended — whereas the install script above needs neither:

npm i -g @globant/coda

Once the install command finishes, head to Connect a Provider to choose your launch mode and connect your first provider.

Keeping CODA up to date

To upgrade later, run coda upgrade from your terminal, or /upgrade from inside the TUI. CODA picks the right mechanism automatically based on how you installed it:

• Installed via npm → it upgrades through npm.
• Installed via the script → it swaps in the latest native binary under ~/.coda/bin.

Troubleshooting

On Windows, coda: The term 'coda' is not recognized as a name of a cmdlet, function, script file, or executable program.

This is expected on Windows right after installing — PowerShell hasn't picked up the updated PATH yet. Just close and reopen your terminal (or open a new tab) and try again.

What's next

With CODA installed, the next step is to Connect a Provider — pick your launch mode, choose your Glob.AI environment, and sign in. Then head to Quick Start to open CODA in a real project and run your first prompt.

Connect a Provider

A provider is the AI backend CODA talks to. You connect one the first time you launch CODA — before you can run a prompt — through a setup wizard (titled CODA setup) that opens automatically. This page explains each choice so you land on the right one. You can reopen the wizard later — see Reconfigure.

Launch coda

coda --globant

If you're a Globant employee working on client projects, internal tooling, or the corporate network, launch with the --globant flag on first launch:

coda --globant

The wizard first asks you to pick between Glob.AI OS and Custom provider. If you choose Glob.AI OS, you'll see an instance picker:

If you select Other, the wizard will ask for:

1. Profile name — a short label for this connection (e.g. my-org).
2. Base URL — the root URL of your Glob.AI OS instance (e.g. https://ai.my-org.com).
3. API key — your API key for that instance.

CODA creates a named profile in your config. The key is stored in ~/.coda/.secrets as CODA_GEAI_OTHER_<PROFILE>_API_KEY.

--globant is sticky. Once set, this flag persists in your config — future launches of coda (without the flag) will still show the instance picker. To revert run coda --no-globant.

coda

If you're not a Globant employee, launch CODA without any flags:

coda

The wizard first asks you to pick between Glob.AI OS and Custom provider. If you choose Glob.AI OS, CODA routes you directly to SaaS Europe — no instance picker.

Authenticate with Glob.AI OS

Once an instance is selected (or auto-selected), you authenticate:

• OAuth / Login (recommended) — CODA opens your browser, you sign in with your Globant account, and the session is stored for you. No keys to copy or rotate. After sign-in, if you have more than one project assigned in that environment, you'll be asked to select your organization and project so CODA knows which workspace to use.
• API Key — paste or type your key (the input is hidden), then press Enter. Corp and custom instances use this path exclusively.

API keys are stored in ~/.coda/.secrets, separate from your config and never committed to Git.

Use a custom provider (non-Glob.AI OS)

At the first wizard screen, pick Custom provider and choose the type:

• OpenAI-compatible — enter a profile name, the base URL, and an API key. Works with any OpenAI-compatible endpoint.
• Ollama — point CODA at your local server (no API key needed).

Reconfigure

To change providers later, run /providers inside a session or coda --reconfigure from your terminal. Both open the same wizard. Changes take effect after a restart.

Switch between configured profiles

Once you have more than one profile set up, use /switch-profile inside a session to change which one is active. The switch takes effect on next launch.

For switching the active project within a profile (when using Glob.AI OAuth), use /project — see Switch-profile vs /project in the Configuration page for the difference.

What's next

With a provider connected, head to Quick Start to run your first prompt. For where credentials and settings live, see Configuration.

Quick Start

This guide takes you from a fresh CODA install to a real working session in under five minutes. You'll open CODA in a project, connect a provider, and run prompts that actually do something useful.

1. Open CODA in your project

Always launch CODA from your project's root directory. That's how it knows what codebase to work with.

Globant employees — first-time setup

The first time you launch CODA, you must run:

coda --globant

This allows you to select and connect to your Globant instance (Clients, Corp, or SaaS Europe). Once the provider is configured, the --globant flag is saved and future launches only require coda.

Not a Globant employee? Launch CODA directly:

coda

For the complete first setup flow, see Connect a Provider.

Running coda opens the interactive terminal UI (TUI) — the full-screen mode you'll use day-to-day. (CODA can also run headless for scripts or inside your editor; see Ways to Run CODA.)

2. Try these prompts

Here are example prompts that work well for a first session. Start with the ones that feel most relevant to you.

Understand what you're looking at

What is the main entry point of this project and how is it structured?

Create an implementation plan

Create a plan to add the X, Y, and Z capabilities to this feature. Don't change files yet — first explain the affected modules, risks, and test strategy.

CODA also ships with a built-in plan skill for this. Just ask naturally as above — CODA picks it up automatically. The /plan slash command is also available if you want to trigger it explicitly.

Review a pull request

Review this PR and summarize the main risks, missing tests, and any code-quality issues: <pull-request-url>

Diagnose a reported bug

Diagnose this bug report and trace the most likely root cause in the codebase: <github-issue-url>

Search for code smells

Search the codebase for code smells around error handling, duplicated logic, and overly large functions. Report findings first; don't edit anything yet.

3. Review what CODA does

When CODA wants to run a shell command or write to a file, it shows you what it's about to do and asks for approval (depending on your bash approval settings). You can:

• Press Y to approve and continue
• Press N to skip that step
• Press Esc to interrupt the current turn entirely

If CODA goes in the wrong direction, interrupt early — don't let it keep going. Interrupting and redirecting is faster than undoing a lot of changes.

4. Undo anything

CODA takes a checkpoint (a file snapshot) before every turn — that is, before CODA starts acting on the message you just sent. If something goes wrong, restoring that checkpoint takes your files back to the state they were in right before that message was processed:

/timeline

This opens the timeline picker (you can also type /rewind, or press Esc twice when the chat input is empty). Select any point to restore your files to that state.

Tip — give CODA your project's rules. Run /init to generate an AGENTS.md: project-specific instructions for the agent (coding conventions, how to run tests, areas to avoid, etc.). It's optional, but it makes CODA follow your team's conventions. Review the file and edit anything it missed. By default it's added to .gitignore (local only) — if you want the whole team to benefit, remove it from .gitignore and commit it.

What's next

• Understand a Codebase — more prompts for exploring unfamiliar code
• Make Changes Safely — checkpoints, approvals, and how to undo
• Configuration — switch providers, tune settings, manage secrets

Configuration

CODA is configured from within the tool itself — you normally don't edit files by hand. Commands like /providers and /settings write your choices to a layered config. This page explains how that works and where everything lives.

Profiles, /switch-profile, and /project

When you connect to a provider through the wizard, CODA creates a profile — a named configuration entry that stores the instance URL, auth method, and a reference to your credentials. You can have multiple profiles (one per Glob.AI environment, plus local Ollama, etc.).

/providers — add or edit provider profiles

/providers (or coda --reconfigure from your terminal) opens the setup wizard to add a new provider profile or edit an existing one. Changes take effect after a restart.

/switch-profile — change which provider profile is active

/switch-profile lets you move from one provider profile to another — for example, from the Clients instance to Corp. It opens a visual picker where you select the profile you want. The switch is persisted and takes effect on the next launch — the current session continues with the existing profile until you restart.

/project — change which project within a profile

/project operates within your current provider profile. It opens a visual picker to switch to a different Glob.AI OS project or organization — without changing the instance or credentials. The switch is live (no restart required).

/project only works with Glob.AI OAuth profiles. It does not apply to API-key-only profiles (Corp), custom instances, or non-Glob.AI providers.

When to use which

Where settings live

Settings cascade in priority order — project settings override user settings, and CLI flags override everything:

Common settings to change

Some settings can be adjusted from the settings panel. Open it from inside CODA:

/settings

Bash approval level — open Bash Tool Preferences to control how many shell commands CODA can run without asking you first. There are four levels:

• safe — only read-only commands run automatically; everything else asks.
• low — the default; a conservative set of safe commands is auto-approved.
• medium — more commands run without prompting.
• high — everything is auto-approved except destructive operations.

The same screen lets you pick the shell CODA uses (auto, bash, powershell, or wsl).

Compaction — to keep context fresh, CODA can automatically condense older conversation before it runs out of room. Tune it under Context Compaction:

• Scope — apply your changes globally or to the current project (project overrides global).
• Enable / disable — turn automatic compaction on or off. With it off, you can still compact on demand with /compact.
• Threshold — how full the context can get (as a percentage) before CODA condenses.
• Retain fraction — how much of the most recent conversation is kept intact when condensing; older messages are summarized.

Chat input — choose what happens when you send a message while CODA is already working: Queue message waits until the current turn finishes (default), while Steer message sends your message as the next input to guide the active flow. In /settings, this appears under Composer. See Make Changes Safely for details.

Theme — switch the look of the UI between classic and modern under UI Theme.

See the full Configuration Reference for every available option.

Ways to Run CODA

There are three ways to run CODA — all the same agent, with the same tools, approvals, and model. Pick the one that fits the job.

Which one to use

Interactive (TUI)

The interactive TUI is how most people use CODA. Open it in your project, start a conversation, and work iteratively — reviewing every change before it happens, asking follow-ups, and navigating the session history.

cd /path/to/your/project
coda

Use slash commands to control the session: /sessions, /timeline, /settings, /compact, and more. See the Commands & Flags reference for the full list.

Headless (Batch)

Batch mode is for automation. Pass a prompt, CODA runs it, and exits with a non-zero code if something goes wrong — which makes it easy to use in scripts and CI.

coda -p "Run the test suite and report failures" --auto-approve all

See Automate with Batch Mode for examples and important flags.

Editor (ACP)

CODA can also run inside your editor through the Agent Client Protocol (ACP) — an open standard, so it works with any ACP-compatible editor (for example Zed and JetBrains IDEs). Edits, terminal commands, and approvals all use the editor's native UI.

See Use CODA in Your Editor (ACP) for setup.

Understand a Codebase

Whether you're onboarding to a new repo or diving into a part of your own codebase you haven't touched in months, CODA can get you oriented fast. This guide shows you how to use CODA as an exploration tool — before writing a single line of code.

Before you start

Launch CODA from the project root and let it explore freely. Don't give it tasks yet — ask it questions. The more context it builds up, the better its answers get.

cd /path/to/project
coda

Get oriented quickly

Start with the big picture before zooming in on specifics.

Understand the overall structure

What is the main entry point of this project and how is it structured?

Map the key flows

Trace the full request lifecycle from an incoming HTTP request to the database and back. Which files are involved?

Understand how a specific feature works

How does authentication work in this project? Walk me through the full flow.

Dig into specifics

Once you have the big picture, use CODA to go deeper on the areas you care about.

Understand a module before changing it

Before I touch the billing module, explain how it works. What are its dependencies? What would break if I changed the calculate_invoice function?

Find where something is implemented

Where is the rate limiting logic implemented? Is it in middleware or inside the controllers?

Understand a bug before fixing it

Users are reporting that their session expires too quickly. Without making any changes, trace the session timeout logic and tell me where the problem might be.

Plan before editing

One of the best uses of CODA's exploration mode is planning a change before you make it. Ask CODA to map the impact of a change so you don't miss anything.

I want to add soft-delete support to the User model. Without making any changes, list every file I would need to touch and explain why each one is affected.

What's the minimal set of changes I'd need to make to support multi-tenancy in this project?

Tips for better exploration

• Be specific about what you want to know. "How does auth work?" is fine, but "How does the OAuth refresh token flow work specifically?" gets you a better answer.
• Ask follow-up questions. CODA builds context as the session progresses. If the first answer is too high-level, ask it to go deeper on the part that matters.
• Don't let it make changes during exploration. If CODA offers to fix something while explaining it, say "just explain for now, don't change anything."
• Delegate broad exploration on large repos. Instead of flooding your main session, ask naturally for a broad exploration — for example: "Map how billing connects to the payment provider and report back a summary; don't edit anything." CODA can decide to delegate that work to the built-in explore agent and bring the summary back to your main session. See Agents for more on delegated work.

Make Changes Safely

CODA is designed for real work on real codebases — which means it needs to be safe to use. This guide explains how CODA protects your work, how to stay in control while it makes changes, and how to undo anything that goes wrong.

Checkpoints: your undo button

Before each turn, CODA takes a checkpoint — a snapshot of your files before it acts on your latest message. Restoring that checkpoint brings the worktree back to the state it had right before that message was processed. To see and restore checkpoints, open the timeline picker with /timeline (or press Esc twice) and select the point to restore to.

For how checkpoints work in detail — the shadow repo, Git requirements, and how restoring rewinds the conversation — see Sessions & Checkpoints.

Approve commands as they run

When CODA wants to run a shell command, it shows you what it's about to execute and waits for your approval — press Y to allow it or N to skip it. By default, CODA auto-approves low-risk commands (like git status or cat) and asks before anything that writes or deletes files.

How much runs without asking depends on your bash approval level, which you set from /settings → Bash Tool Preferences:

See Configuration for more on adjusting this per project.

Interrupt early if something looks wrong

If you see CODA going in the wrong direction, don't wait for it to finish — interrupt as soon as you notice:

• Press Esc to stop the current turn
• Then redirect: "Stop — I didn't mean to change that file. Undo those changes and let's try a different approach."

The earlier you interrupt, the easier it is to recover. Letting CODA run to completion and then asking it to undo everything is much messier than stopping it mid-stream.

Send a message while CODA is working

You don't have to stop the turn to react. You can type while CODA is busy, and a setting controls what happens when you hit Enter. Choose it from /settings → Composer. This controls the chat input behavior while CODA is busy:

• Queue (default) — your message waits and is delivered as the next turn once the current one finishes.
• Steer — your message is injected into the run in progress, nudging CODA mid-turn without interrupting it.

If you queued messages and change your mind, press Ctrl+G to clear the queue.

A safe workflow for bigger changes

For anything non-trivial, use this pattern:

1. Explore first, change later. Ask CODA to explain what it would do before it does it: "List the files you'd need to change for X, but don't make any edits yet."
2. Work in small steps. Instead of "implement the whole feature", break it into "add the model", then "add the controller", then "add the tests". Checkpoint between each.
3. Review after each step. Use /timeline to verify what changed before moving to the next step.
4. Test often. Ask CODA to run your test suite after each significant change: "Run the tests for the billing module now."

Common undo scenarios

CODA edited the wrong file

Undo the last change you made to UserService.java — you edited the wrong method.

A whole batch of changes went wrong

/timeline

Select the snapshot from before the bad changes. CODA restores your files to that state.

You want to start the session over

/new

Starts a fresh session. The old session is still saved and resumable — see Sessions & Checkpoints.

Collaborate with Your Team

CODA works best when the whole team uses it consistently. This guide covers how to share conventions, skills, and configuration so every developer on the project gets the same quality of assistance.

Start with AGENTS.md

AGENTS.md is the most important file for team collaboration. CODA reads it at the start of every session and uses it to understand your project's conventions — coding style, testing approach, which areas to avoid, how to run the quality checks.

Create or update it with /init and then edit it to add what CODA missed. A typical AGENTS.md looks like this:

# AGENTS.md

## Project conventions
- Use TypeScript strict mode everywhere
- All database queries must use parameterized statements
- New features must include unit tests and at least one integration test

## How to run tests
  pnpm test              # unit tests
  pnpm test:integration  # integration tests
  pnpm lint              # linting
  pnpm type-check        # TypeScript check

## Quality gate — always run before finishing a task
  pnpm lint && pnpm type-check && pnpm test

## Do not change
- The public API in src/api/v1/ without team approval
- The database schema without a migration

Commit AGENTS.md to Git. Every developer who runs CODA in this project gets these conventions automatically.

Share skills across the team

Skills are per-project when placed in <project>/.coda/skills/. Commit them to the repository and everyone can invoke them — or manage them from the /skills manager inside CODA.

Good candidates for shared skills:

• PR review checklists specific to your project
• Debugging workflows for common issues
• Documentation generation templates
• Deployment pre-flight checklists

Once committed, any developer on the team can invoke them by name:

/pr-review
/debug-api-error
/generate-docs

What to commit (and what not to)

The most valuable things to share live in the repo and apply to everyone who clones it:

• AGENTS.md — your project conventions and quality gates.
• Skills in <project>/.coda/skills/ — shared workflows the whole team can invoke.
• MCP servers in <project>/.coda/mcp.json — the external services this project connects to.

A project-level <project>/.coda/config.json is also safe to commit — it never holds secrets (those live in ~/.coda/.secrets, which is never committed). But be selective about what you put there:

• Don't commit the active provider. Which provider you use (a specific Glob.AI instance, or a local Ollama) is a personal, machine-specific choice, and provider profiles are defined in each developer's own global config. Pinning it in the repo can break teammates who don't have that profile.
• Think twice before committing an elevated bash approval level. Raising autoApproveLevel for the whole project means everyone who clones the repo runs more commands without being asked — a safety trade-off your team should agree on first.

In short: share conventions and workflows, keep personal and security preferences local.

Working in a monorepo

CODA loads exactly one AGENTS.md — the one in the directory where you launch it. There's no upward directory walk and no merging of parent files.

In a monorepo, launch CODA from the package directory you're working in:

cd packages/billing
coda   # loads packages/billing/AGENTS.md

Put conventions that apply everywhere in each package's AGENTS.md, or maintain a root-level one and symlink it into each package.

Automate with Batch Mode

Batch mode (also called headless mode) lets you run CODA from a shell script or CI pipeline — no terminal UI, no interaction. You give it a prompt, it runs, and it exits. This is how you integrate CODA into automated workflows.

When to use batch mode

• Running CODA as a step in a CI pipeline (generate docs, run a code review, apply a linting fix)
• Scripting repetitive tasks across multiple repos
• Triggering CODA from a webhook or external event
• Running a long analysis job and checking the result later

For day-to-day coding where you want to review changes as they happen, use the interactive TUI instead.

Basic usage

The simplest batch run: pass a prompt with -p.

cd /path/to/project
coda -p "Summarize what this repo does in five bullet points"

CODA runs, prints the result, and exits. No UI, no interaction.

Practical examples

Generate a changelog from recent commits

coda -p "Look at the last 20 git commits and write a CHANGELOG entry for this week's changes."

Check for security issues before merging

coda -p "Review the changes in this PR for potential security issues. Focus on input validation, SQL queries, and authentication checks."

Run from a prompt file

For longer or more structured prompts, put the prompt in a file:

coda --prompt-file ./scripts/review-prompt.txt

Use in a CI pipeline

#!/bin/bash
coda -p "Run the test suite and report any failures" \
     --auto-approve all \
     --output json \
     --timeout 600000

EXIT=$?
if [ $EXIT -ne 0 ]; then
  echo "CODA run failed with exit code $EXIT"
  exit $EXIT
fi

Important flags for automation

Approvals in CI. In headless mode --auto-approve defaults to all, so CODA runs without stopping for prompts. Pass --auto-approve none if you instead want it to refuse anything that would need approval and abort on the first such request. For finer control over which shell commands run, also set bash.autoApproveLevel in config.json (it defaults to high in headless mode).

What batch mode can't do

Batch mode runs a single turn — one prompt, one response. It doesn't support multi-turn conversation or interactive review. For tasks that require back-and-forth, use the interactive TUI.

Use CODA in Your Editor (ACP)

CODA works inside any editor that supports the Agent Client Protocol (ACP) — an open standard, so you are not tied to a fixed list. This guide covers Zed and JetBrains IDEs.

You chat in the editor's AI panel, and edits, terminal commands, and approvals all use the editor's native UI. It is the same agent — tools, approvals, and model — that you run in the terminal; the editor just launches coda --acp behind the scenes.

Prerequisites

Before configuring any editor, get these three things ready:

1. Install CODA so the coda binary is available, then note its absolute path — run which coda on macOS/Linux, or where coda on Windows. Use that absolute path in the editor config — editor-launched subprocesses often do not inherit your shell PATH.
2. Authenticate once in a terminal. CODA uses interactive OAuth, which the editor's subprocess cannot perform. Run coda once in a terminal and complete sign-in; credentials are saved so coda --acp can reuse them.
3. ACP is enabled by default, so there is nothing to turn on. To opt out, set acp.enabled: false in your CODA config (see CODA config below).

Zed

Zed runs on macOS, Linux, and Windows. Open the settings file with the command palette (Zed: Open Settings File) or edit it directly. The location depends on your OS:

• macOS / Linux: ~/.config/zed/settings.json
• Windows: %APPDATA%\Zed\settings.json

Add CODA under agent_servers, setting command to your coda binary path (macOS/Linux):

{
  "agent_servers": {
    "CODA": {
      "type": "custom",
      "command": "/Users/you/.coda/bin/coda",
      "args": ["--acp"],
      "env": {}
    }
  }
}

On Windows, point command at coda.exe:

{
  "agent_servers": {
    "CODA": {
      "type": "custom",
      "command": "C:/Users/you/.coda/bin/coda.exe",
      "args": ["--acp"],
      "env": {}
    }
  }
}

Then open the agent panel, click +, and pick CODA to start a thread.

Reference: Zed External Agents docs.

JetBrains (IntelliJ, WebStorm, PyCharm, …)

In the AI Chat tool window, open the ⋯ menu and choose Add Custom Agent. JetBrains opens acp.json (~/.jetbrains/acp.json, or C:\Users\<you>\.jetbrains\acp.json on Windows). Add CODA under agent_servers, pointing command at your coda binary (macOS/Linux):

{
  "default_mcp_settings": {},
  "agent_servers": {
    "CODA": {
      "command": "/Users/you/.coda/bin/coda",
      "args": ["--acp"],
      "env": {}
    }
  }
}

On Windows, point command at coda.exe:

{
  "default_mcp_settings": {},
  "agent_servers": {
    "CODA": {
      "command": "C:/Users/you/.coda/bin/coda.exe",
      "args": ["--acp"],
      "env": {}
    }
  }
}

Then select CODA in the AI Chat agent picker.

Reference: JetBrains Add ACP agents docs.

CODA config

ACP is enabled by default, so this section is optional. The only relevant knob lives in your CODA config file — ~/.coda/config.json for your personal defaults, or <project>/.coda/config.json for a single project (see Configuration):

{
  "acp": {
    "enabled": true
  }
}

Set "enabled": false to opt out. The TUI, batch, and print modes are unaffected either way.

What works

When running through ACP, CODA integrates with the editor's native UI:

• Streaming — assistant text and reasoning stream into the editor's chat panel.
• Native diffs — file edits render in the editor's own diff/review UI.
• Editor terminal — commands run in the IDE's terminal pane, when the editor advertises the terminal capability.
• Permissions — tool approvals use the editor's permission prompts, and the session-mode dropdown maps to CODA's autonomy controls. The three modes are Default (ask before risky actions), Plan (CODA proposes without editing), and Accept Edits (apply file edits without prompting).

Troubleshooting

• "command not found" / agent won't start — use the absolute path from which coda; don't rely on coda being on the editor's PATH.
• Auth prompts / immediate failures — run coda once in a terminal to sign in (Prerequisites #2), then retry in the editor.
• coda --acp exits immediately with a config message — you have acp.enabled: false set; remove it or set it to true.

Notes

• The config formats above follow the editors' official docs (Zed agent_servers, JetBrains ~/.jetbrains/acp.json) as of mid-2026. Check the linked pages if an editor changes its format.
• ACP Registry one-click install is not yet available for CODA — use the manual config above. A registry listing is a planned follow-up.

View & Share Logs

CODA writes structured logs to disk so you can troubleshoot what happened in a session — and share a safe, redacted bundle with support when you need help. Secrets are scrubbed before anything is written, so logs are safe to read and share.

What you get

• coda logs — a full-screen log viewer in your terminal, or a plain text / JSON stream when piped.
• Filtering by level, service, and time, plus a live --follow tail.
• Secret redaction at the source — tokens, keys, passwords, and Bearer/sk-/ghp_-style values never reach disk.
• coda logs export — a local, redacted, path-scrubbed bundle for support (nothing is ever uploaded).
• Per-service log levels so you can turn up detail only where you need it.
• coda logs-demo — a few-second self-test of the whole logging pipeline.

Viewing logs

coda logs              # interactive viewer (in a terminal)
coda logs | less       # plain text stream (when piped)
coda logs --json       # raw JSON lines
coda logs --follow     # tail new entries live

In an interactive terminal, coda logs opens a full-screen viewer with aligned TIME LEVEL SERVICE MESSAGE columns. Only warn and error rows are colored, so problems stand out.

When piped or non-interactive, the same window streams as one entry per line (or --json for raw lines, --plain to disable color), so grep and less work as usual.

Filtering

All filters work in both the viewer and the stream:

Where logs live

Logs are stored under ~/.coda/logs/ (relocatable with CODA_HOME). The live file is coda.log; on rotation it shifts to a numbered file (coda.log.1 … coda.log.7). Logs rotate daily and at 50 MB, keeping the 7 most recent files. coda logs reads across all of them automatically, newest first. Each line is one JSON object: an ISO-8601 time, a level, the service name, the msg, and any structured fields.

Secrets never hit disk

Every entry is scrubbed as it's written:

• Secret-looking keys (authorization, token, apiKey, secret, password, cookie, …) have their value replaced with [REDACTED].
• Secret-looking values anywhere in a string (Bearer …, sk-…, ghp_…, AKIA…, JWTs, private-key blocks) are scrubbed — even inside a longer message like a shell command.
• Counters like token usage are kept; only string secrets are masked.

Built-in redaction is always on and can't be disabled. To add rules (extra deny-keys, key substrings, or value patterns), set logging.redact in your config — they merge on top of the built-ins.

Log levels

You can control per-service detail two ways. The LOG_LEVEL environment variable wins over config for the same service.

• Persistent — in your config: logging.level (global default) and logging.levels (per service).
• Ad-hoc — the LOG_LEVEL env var (Rust-style; a bare token sets the global floor):

LOG_LEVEL=info,core.agent.step:debug,core.tools:warn coda

By default, info carries lifecycle events (a turn starting and finishing); per-operation detail (each agent step, tool call, and file op) is debug. A per-service entry always beats the global default.

The viewer gate

Raw log viewing is controlled by logging.rawViewer.enabled. Left unset, it defaults on during development and off in a shipped release build. When it's off, coda logs declines and points you at the export below (which is never gated). Redaction protects secrets either way — the gate just keeps raw logs from being browsed casually in a release.

Sharing logs with support

coda logs export [--since … | --lines … | --keep-paths]

This writes a local, redacted bundle to ~/.coda/exports/ and prints the path — nothing is uploaded. Each entry is redacted a second time (also catching logs written by an older version), and absolute paths are rewritten so your username and home directory don't leak (--keep-paths opts out). The bundle records the CODA version, OS/arch, and session/turn ids — no identity. Review the file, then share it.

Self-test

coda logs-demo

Runs the whole pipeline end to end (build redacted entries → read → render → filter → export) against a throwaway directory and prints PASS / FAIL in a few seconds — a quick way to confirm logging works after an install or upgrade.

See also

• Commands & Flags — the full command and flag reference.
• Configuration — where the logging.* settings live.

How CODA Works

Understanding what CODA does under the hood helps you use it more effectively — and troubleshoot it when it behaves unexpectedly.

The agent loop: how CODA acts

CODA doesn't just generate text — it works in a loop. Each turn, it reads your request and the context so far, decides on a next step, calls a tool to act, observes the result, and repeats until the task is done. You stay in control at every step: anything risky pauses for your approval (see Permissions & Approvals).

CODA picks which tools to use automatically based on the task — you don't tell it "search now" or "run the tests", it figures that out:

CODA always reads your files live from disk, not from a cached index — so it works with what's currently there, never a stale snapshot.

What CODA knows

Within a session, CODA builds up context — everything you've said and everything it has read or done so far. That's why later turns are often sharper than earlier ones: it has more to work with. Two things persist across sessions: AGENTS.md, the project conventions you give it (see Collaborate with Your Team), and MEMORY.md, the durable facts CODA learns on its own (see Memory).

Compaction: keeping context fresh

Long sessions accumulate a lot of history. Once the conversation reaches a certain size, CODA automatically condenses older messages into a summary (compaction) while keeping recent messages verbatim. This keeps the session running smoothly without losing important context.

You can also trigger compaction manually before switching topics:

/compact

If you'd rather control when this happens — for example while debugging a problem where CODA seems to "forget" something — open /settings → Context Compaction to disable automatic compaction or adjust when it kicks in. See Configuration for details.

Permissions & Approvals

CODA can read files, run shell commands, and edit your code — but it asks before doing anything risky. This human-in-the-loop (HITL) design keeps you in control: CODA proposes an action, you approve or skip it, and nothing irreversible happens behind your back.

How approvals work

When CODA wants to do something that could change your system, it pauses and shows you exactly what it's about to do. In the interactive TUI you answer with a single key:

• Y — allow this action and continue.
• N — skip it; CODA carries on without running that action.

How often CODA stops to ask depends on your settings. The goal is to auto-approve the safe, routine things (reading files, listing directories) and pause on the things that write, delete, or reach outside your project.

Bash approval levels

The most common approval control is the bash approval level — it decides how many shell commands CODA can run without asking. Set it from /settings → Bash Tool Preferences:

Even at high, commands that match CODA's blocked patterns are refused outright — they're never offered for approval. This includes clearly catastrophic operations on both Unix (rm -rf, fork bombs, dd to a disk device, mkfs) and PowerShell (Remove-Item recursive-force on a drive, Format-Volume, Clear-Disk, diskpart). Lowering the level is the safest choice when you're working in an unfamiliar or sensitive repo.

Choosing the shell

CODA runs bash commands through a shell you can pick from the same /settings → Bash Tool Preferences screen. The shell mode can be auto (let CODA detect the best option), or you can pin it to bash, powershell, or wsl — handy on Windows where the default isn't always what you want.

Other actions that ask first

Bash isn't the only thing gated by approvals. CODA also pauses before:

• Overwriting a file it never read this session — an anti-clobber guard. If CODA didn't read a file before writing to it, it asks first so it can't silently clobber work it hasn't seen.
• Consolidating memory — when CODA rewrites its MEMORY.md notes, it asks before replacing them.
• MCP and other tools — tools from connected MCP servers go through the same approval flow as everything else, so you stay in control of what they do.

Custom gates with hooks

Beyond the built-in approvals, you can enforce your own policies with a PreToolUse hook. A hook is a script that runs before a tool executes and can block it — for example, refusing any git push to main, or any command touching a protected path. Blocking is fail-closed: if your hook errors or times out, the tool call is blocked rather than let through. See Hooks for the events and configuration.

Approvals in headless (batch) mode

Headless runs can't show you a prompt, so the rules are stricter and more autonomous by design:

• --auto-approve defaults to all. Unless you pass --auto-approve none, a batch run approves every action on its own so it doesn't hang. This is the most important default to understand before running CODA unattended.
• --auto-approve none aborts on the first prompt. Since there's no one to answer, if the run hits something that would need approval it stops with an error instead of waiting.
• Bash defaults to the high tier in headless (versus low interactively), so routine commands run without stopping.
• The ask_user tool ends the run. If the agent tries to ask you a question, the batch run aborts with an error — there's no one to answer.

You control this from the command line when you launch a batch run:

# Set the bash approval level for this run
coda -p "Run the test suite and report failures" --bash-security high

# Require approval — the run aborts if it hits something risky
coda -p "Review the diff and comment" --auto-approve none

Because all is the default, an unattended run will not stop to ask — even for risky commands — unless you pass --auto-approve none. Use the default only when you trust the prompt and the repo.

Where to set it

• From inside CODA: /settings → Bash Tool Preferences (applies globally or per project).
• Per project: project-level config overrides your personal defaults — see Configuration.
• For a single run: the --bash-security and --auto-approve flags (see Commands & Flags).

See also

• Make Changes Safely — staying in control while CODA edits code.
• How CODA Works — tools, memory, and the agent loop.
• Configuration — where settings live and how they cascade.

Agents

Agents let CODA delegate work to itself. You give a named profile and a task, and CODA starts a child session — its own conversation, in the same project — that works through the task independently and reports back. It's like dispatching a specialist to handle one part of the job while your main session keeps going.

What agents are

An agent run is a delegated task handled by a child CODA session. You hand it:

• A named profile — a reusable definition that describes how the agent should behave (its instructions, and optionally which model and tools it uses).
• A task — what you want it to accomplish.

CODA tracks each run through its lifecycle — queued → running → completed (or failed) — and you can inspect a run, stop it, or open its child transcript at any time from the parent session.

CODA can also start agents on its own. When a task benefits from delegation — say, exploring a large repo while the main session keeps working — the model uses the built-in run_agent, wait_agents, and cancel_agent tools to spin up and manage runs the same way you do with slash commands.

Agents that ship with CODA

You don't have to write an agent to start using them — CODA bundles a couple of ready-made ones, synced into ~/.coda/agents/ automatically:

• coda-help — your in-app documentation assistant. Ask CODA anything about how to use it ("how do I undo a change?", "how does compaction work?") and it answers by searching the local user guide. Just ask in plain language — CODA detects the question is about itself and delegates to coda-help automatically.
• explore — a codebase-exploration specialist for mapping an unfamiliar area and reporting back a summary without making edits (handy for large repos — see Understand a Codebase).

These are just regular agent definitions, so you can read, copy, or adapt them like any other.

Defining an agent

Agent definitions are Markdown files with YAML frontmatter. The body of the file becomes the agent's instructions.

---
name: explore
description: Explore one area of the codebase and report back a concise summary.
---

You are a codebase exploration specialist. Given an area or question:

1. Map the relevant files and how they fit together.
2. Trace the key data flows.
3. Report back a concise summary — no edits.

Required frontmatter: name and description.

Common optional fields: model (or inherit to use the main session's model), tools / disallowedTools, background, and color.

A few more fields — maxTurns, effort, permissionMode, skills, memory, and isolation — are accepted for compatibility with agent definitions imported from other tools, but aren't enforced yet. You can leave them in place; CODA just won't act on them.

Where CODA looks for definitions

CODA discovers agents from several locations. The first match for a given name wins; duplicates elsewhere are reported as diagnostics only:

1. <project>/.coda/agents/ — walking up from the project directory toward your home directory, so each ancestor folder can contribute definitions.
2. ~/.coda/agents/ — your personal, user-wide library.
3. Plugin agent directories — contributed by installed plugins.

Files use the .md (or .markdown) extension. Commit project agents to Git so the whole team shares them.

Running and managing agents

Manage everything from inside CODA with the /agents manager:

/agents

Foreground vs background

By default, runs are background — they proceed while you keep chatting in the main session. Add --foreground to block until the run finishes and print its details when it's done. Background is best for parallel work; foreground is best when you need the result before continuing.

Configuration

Agent behavior is controlled by the agents block in your config (global and/or project):

By default, delegated runs use the same model as your main session unless a definition sets model explicitly. Instead of naming an exact model, a run can request a quality tier — "fast" (cheapest, for high-volume work), "smart" (balanced), or "deep" (strongest) — and CODA resolves it to the matching model configured for the active provider.

Good to know

A few limitations worth keeping in mind:

• No nested agents — a child session can't spawn further agent runs; those tools are removed inside it.
• No background runs in headless — background delegation needs an interactive UI, so asking for a background run in a headless (-p) session fails right away. Foreground runs still work.
• Approvals — if a child run needs your approval and you deny it (or can't answer), the run fails with a clear message.
• First definition wins — if the same name exists in two folders, only the first discovered is used.

See also

• Workflows — orchestrate many agents at once (fan-out, pipelines, loops).
• Extend CODA — skills, extensions, plugins, and MCP.
• Tools Reference — the run_agent family and the rest of CODA's tools.
• Understand a Codebase — delegating broad exploration to a sub-agent.

Sessions & Checkpoints

Every time you run CODA, it creates a session — a persistent record of everything that happened: your prompts, CODA's responses, every file it read, every command it ran. Sessions let you pick up where you left off, and checkpoints let you undo what went wrong.

Resume where you left off

When you exit CODA (Ctrl+C twice or /exit), the session is saved. To continue it later:

# Resume the last session
coda --lastsession

# Resume a specific session by ID
coda --session-id <id>

When you exit, CODA prints the exact command to resume — coda --session-id <id> — ready to copy and paste. You can also browse and switch sessions from inside the TUI:

/sessions

Start fresh without losing the old session

To start a new conversation without exiting CODA:

/new

This opens a new session. The previous session is saved and can be resumed later — nothing is lost.

Checkpoints: undo at any point

CODA takes a checkpoint (a file snapshot) before each turn — before it acts on the message you just sent. Snapshots are stored in a private shadow repository under ~/.coda/checkpoints/, so your project's own Git history and commits are never touched.

Think of a checkpoint as "the state from before this message ran." If a prompt leads CODA in the wrong direction, restore the checkpoint for that turn to return your files to the exact state they had before CODA processed it.

To view and restore checkpoints, open the timeline picker:

/timeline

You can also type /rewind or press Esc twice when the chat input is empty. Select any checkpoint to restore your files to that exact state — this is your undo button for anything CODA does to your codebase. Restoring also rewinds the conversation back to that point. (Your chat history isn't altered by editing files; only a restore rewinds it.)

Checkpoints require Git 2.5.0+. If Git is unavailable or too old, checkpoints are disabled automatically and CODA tells you at startup. Checkpoints are a TUI feature: the /timeline picker doesn't exist in headless (batch) mode, so there's no way to restore there. They're off by default in batch; you can force snapshots on with --checkpoints=true for an audit trail, but you won't be able to roll back without the interactive UI.

What a snapshot captures (and what it skips)

A checkpoint records your project worktree files at that moment — but not everything. CODA always skips build artifacts, caches, and a few protected paths so snapshots stay fast and safe:

.git, .coda/sessions, .coda/MEMORY.md, .coda/agents, node_modules, .venv, venv, dist, build, .next, .turbo, __pycache__, .pytest_cache, .cache, target, .gradle, and similar.

Two things are deliberately protected:

• .coda/MEMORY.md is excluded at both capture and restore time, so your agent's memory survives every rollback intact.
• .git/ is never touched — your project's own Git history is completely separate.

Exclude your own paths with .codaignore

To keep additional project-local paths out of snapshots, add a .codaignore file at your project root. It uses gitignore syntax (including negations), so you can exclude large data folders, generated output, or anything you don't want captured.

Drift detection

If your worktree has uncaptured changes when you try to restore — your own edits, or agent output from the current turn that hasn't been snapshotted yet — CODA stops the restore so you don't silently lose work. In the /timeline picker, press F to force through the drift if you're sure, or Esc to cancel. The top of the list also has an Undo your last restore entry, in case a restore itself went the wrong way.

Verify checkpoints work

After an install or upgrade, you can smoke-test the whole subsystem against a throwaway project:

coda checkpoints-demo

It runs through snapshot, restore, undo, drift handling, and memory preservation, then exits in a few seconds — no real session needed.

Watch the context fill level

The status bar at the bottom of the TUI shows a context fill percentage. As it approaches 100%, CODA automatically compacts the session history to keep things running — see How CODA Works for how compaction works and how to control it. If a long session starts feeling off, you can run /compact to condense it now, or start a /new session and bring in just the context you need.

Memory

CODA can remember durable facts about you and your projects across sessions. When you share a preference, make a key decision, or correct CODA's behavior, it can save that as a one-line note in a MEMORY.md file and re-read it at the start of every future session — so you don't have to repeat yourself.

Global vs. project memory

There are two memory files, loaded together into every session:

• Global memory — ~/.coda/MEMORY.md. User-wide preferences and facts that apply across all your projects (e.g. "I prefer functional style", "I'm based in Tokyo").
• Project memory — <project>/.coda/MEMORY.md. Facts specific to one repository. Commit it if you want the whole team to share that context.

Memory vs. AGENTS.md

These look similar but serve different purposes, and CODA keeps them separate on purpose:

When CODA discovers a project convention, it suggests adding it to AGENTS.md — not memory. See Collaborate with Your Team for AGENTS.md.

What CODA remembers

CODA saves things that are durable, non-obvious, actionable, and compact — for example personal or workflow preferences, important architectural decisions, and corrections to its behavior. Notes are grouped under named sections: Stable User Preferences, Stable Project Preferences, Important Decisions, Learned Facts, Known Gotchas, Source-of-Truth Pointers, and Things To Re-Validate.

It deliberately does not store ephemeral task state, transient output, conventions that belong in AGENTS.md, anything trivially rediscoverable from the repo, or sensitive data like API keys and passwords.

Review, edit, or clear it

The simplest way is to just ask CODA — "show me your project memory", "update that note about X", or "remove that entry". It reads and rewrites the file for you (a full cleanup asks for your confirmation first).

You can also open ~/.coda/MEMORY.md or <project>/.coda/MEMORY.md in any editor and edit them directly. To wipe memory, empty or delete the file — CODA recreates it from a template the next time it saves something.

Note: CODA reads memory when a session starts. If you edit the file by hand mid-session, start a new session to pick up the change.

Conflicts

If a new note contradicts an existing one, CODA keeps both and marks them with a ⚠️ CONFLICT tag rather than guessing. The next time it notices, it asks you which version to keep and resolves it. If you ever see ⚠️ CONFLICT in a MEMORY.md, that's a cue to pick the right one.

It survives resets and undo

Memory lives in plain files, independent of your session history and checkpoints. Starting a new session doesn't clear it, and restoring a checkpoint never rolls memory back — what CODA learned stays learned, even if you undo the code changes from that turn.

Extend CODA

Out of the box, CODA can read files, run shell commands, and use its built-in tools. When you need more, there are five ways to extend it — from connecting an external service to orchestrating whole fleets of agents. This page is a map; each option has its own page with the details.

Connect external services with MCP

MCP servers give CODA access to external tools — your issue tracker, CI system, database, or any service that exposes an MCP interface. Once connected, CODA uses those tools automatically when they're relevant. → MCP Servers

Teach CODA repeatable processes with skills

Skills are Markdown files that describe a repeatable process, like "how to review a PR." CODA picks the right one automatically when your request matches its description. → Skills

Automate with extensions

Extensions are TypeScript modules that register custom tools and slash commands. Reach for one when you need to integrate an internal system that has no MCP server, or automate logic that doesn't fit in a skill. → Writing Extensions

Share packaged integrations with plugins

Plugins are versioned, installable packages that bundle skills, agents, and MCP servers together behind a manifest. Use them to share a reusable integration across teams or projects. → Plugins

Orchestrate multiple agents with workflows

Workflows coordinate many agents at once — fanning work out in parallel, running pipelines, or looping over a list — for jobs a single agent can't cover well, like a repo-wide audit. → Workflows

MCP Servers

MCP (Model Context Protocol) is an open standard for connecting AI agents to external services. By registering an MCP server, you give CODA access to a new set of tools — querying your issue tracker, driving a browser, calling an internal API, or anything else that exposes an MCP interface. Once a server is connected, CODA discovers its tools and calls them automatically when they're relevant to your request.

Add a server

The easiest way is the /mcp manager inside CODA:

/mcp

From the overlay you can add a server (paste its JSON or open the config in your editor), list configured servers and their connection status, view the tools each one exposes, enable or disable servers for the session, and reload after a change — without hand-editing files outside the app.

To configure servers by hand, add them under mcp.servers in your config file — ~/.coda/config.json for all projects, or <project>/.coda/config.json for one. CODA also reads a standalone mcp.json (with a top-level mcpServers key) at the same locations, which is compatible with other MCP tools.

Server types

A server is either local (CODA runs it as a subprocess) or remote (CODA connects over HTTP). CODA infers the type from the fields you set — command means local, url means remote. Remote servers use the MCP Streamable HTTP transport, so the endpoint at url must speak Streamable HTTP (the older SSE-only transport isn't supported).

{
  "mcp": {
    "servers": {
      "playwright": {
        "command": "npx",
        "args": ["@playwright/mcp@latest"]
      },
      "github": {
        "url": "https://api.github.com/mcp",
        "authorizationToken": "Bearer ${GITHUB_TOKEN}",
        "timeout": 30
      }
    }
  }
}

Common fields: command / args / env for local servers; url, headers, authorizationToken, and timeout for remote ones; and disabled: true to keep a server defined but off. Secrets in env, headers, and authorizationToken can reference variables with ${VAR} (or ${VAR:-default} for a fallback), resolved from your .secrets, project .env, or environment — so you never hard-code a token.

Project config overrides global config when a server has the same name, so a repo can pin its own version of a shared server.

How CODA uses MCP tools

You don't call MCP tools by name. CODA exposes a single gateway tool, mcp_execute, and the system prompt lists every connected server with its available tools. You just describe what you want, and CODA picks the right server and tool. For example, with a GitHub server connected:

Create a GitHub issue titled "NullPointerException in PaymentProcessor.processRefund".

CODA recognizes that the GitHub server exposes an issue-creating tool and calls it for you.

Connection behavior

• Lazy connect — servers connect on your first prompt, not at startup, so launching CODA stays fast.
• Per-session toggles — /mcp enable <server> and /mcp disable <server> turn a server on or off for the current session only, without touching your saved config. These per-session choices are stored separately (in the session's own mcp.json) and take precedence over your global and project config for that session.
• Live reload — after editing config, choose Reload MCP servers in the /mcp overlay; the change applies without restarting.

Useful one-liners: /mcp status (servers + connection state) and /mcp list-tools [server] (the tools a server exposes).

From plugins

A plugin can bundle MCP servers, so installing the plugin registers them for you. Your own config always takes precedence over a plugin's servers when names collide.

Skills

A skill teaches CODA a repeatable process — "how to review a PR", "how to write tests for this project", "how to cut a release". It's a Markdown file with a short YAML header describing what it does, followed by the instructions CODA should follow. Once a skill is in place, CODA uses it automatically whenever your request matches its description — you just ask in plain language.

Create a skill with CODA

The fastest way to make a skill is to let CODA write it for you. CODA ships with a built-in create-skill skill that turns a plain-language description into a ready-to-use SKILL.md — it picks the right scope (project vs. global), sets up the frontmatter, and drafts the steps.

Just describe what you want in plain language — no slash command needed, CODA picks up the request on its own:

create a skill that reviews a PR for test coverage

You can also trigger it explicitly with the /create-skill slash command. Either way, CODA asks a few clarifying questions if needed and writes the file to the correct location for you.

Prefer to author it yourself? The next section covers the file format.

Write a skill

A skill is a SKILL.md file with name and description in its frontmatter, plus the steps in the body:

---
name: pr-review
description: Review a pull request for code quality, test coverage, and potential issues.
---

1. Read the diff carefully.
2. Check that every changed function has test coverage.
3. Flag any SQL queries that aren't parameterized.
4. Note any missing error handling.
5. Summarize the findings in a comment-ready format.

Save it under .coda/skills/ — for example <project>/.coda/skills/pr-review/SKILL.md. The description is what CODA reads to decide when the skill applies, so make it specific.

Two optional frontmatter flags fine-tune visibility: disable-model-invocation: true keeps a skill out of CODA's automatic selection (it can still be run explicitly), and user-invocable: false hides it from the slash-command list (handy for internal helper skills).

Where skills live

CODA discovers skills from two places:

• Project — <project>/.coda/skills/. Commit these so the whole team gets them.
• Global — ~/.coda/skills/. Personal skills, available in every project.

If a project skill and a global skill share the same name, the project one wins.

Use a skill

The main path is automatic: describe the task and CODA matches it to a skill by its description. With the example above in place, just ask:

Review this PR

If you'd rather invoke one explicitly, every skill is also a slash command:

/pr-review

Manage skills

Open the skills manager to browse, enable, disable, and install:

/skills

Quick commands: /skills list shows every skill and its state; /skills enable <name> / /skills disable <name> toggle one for the session; /skills refresh re-scans the folders. To install skills straight from a GitHub repo:

/skills add https://github.com/org/repo

This installs to your global skills by default; add project at the end to install into the current project instead.

Built-in and shared skills

CODA ships with a couple of built-in skills, including plan (gathers context and writes an implementation plan), create-extension (scaffolds an extension for you), and create-skill (helps you write a new skill from scratch — just describe what you want and it generates the SKILL.md for you). Beyond those, the QE team maintains a ready-to-install catalog of 45+ testing skills — see QA & Testing Skills.

Skills can also come bundled in a plugin; those appear alongside your own and are namespaced as plugin-name:skill-name.

QA & Testing Skills

The QE team maintains a ready-to-install catalog of 45+ QA/testing skills that run inside CODA. They cover the whole testing lifecycle — test planning, test-case design, UI/API/mobile automation, performance, accessibility, security, and defect analysis — so you can drive testing work in plain language without leaving your terminal.

These skills live in a dedicated repository: magnifai-gbx/coda-skills. That repo (and its skills-reference.md) is the source of truth for the full, up-to-date list, including each skill's parameters.

Install

Install the skills straight from GitHub, from inside CODA. There are two ways.

Command

To install in one line, use /skills add:

/skills add https://github.com/magnifai-gbx/coda-skills

Optionally add a scope argument to choose where it lands:

For private repos or to avoid GitHub rate limits, set GITHUB_TOKEN (or GH_TOKEN) so the GitHub API fallback can authenticate.

Interactive (skills manager)

Prefer to pick skills one by one? Open the skills manager and choose Install from GitHub (the third option in the menu):

/skills

Then:

1. Select Install from GitHub.
2. Paste the repo URL: https://github.com/magnifai-gbx/coda-skills
3. Choose the destination — project (.coda/skills/) or global (~/.coda/skills/).
4. Pick which skills to install from the checklist (Space to toggle, Enter to confirm).

After installing, run /skills refresh to re-scan the skill directories and /skills list to confirm the new skills are available.

Use

You normally don't need to name a skill. Just describe the action you want and CODA matches it to the right skill automatically (based on each skill's description). For example:

Run the smoke suite against the staging payments API

CODA recognizes this maps to the API testing skill and runs it. If you prefer to be explicit — or want to make sure a specific skill is used — you can still invoke it directly as a slash command:

/g-qe-api-tester run the smoke suite against the staging payments API

What's in the catalog

A sample of the categories covered (see the repo for the complete list):

Authoring new QA skills

If your team wants to add or improve a skill, the contribution guide lives in the repo: read CONTRIBUTING.md and start from the skill-template/ skeleton. For the general mechanics of how skills work in CODA, see Skills.

Writing Extensions

Extensions are TypeScript modules that plug into CODA. Use them when you want CODA to integrate with an internal system that has no MCP server, or to automate a workflow that's too complex for a skill. An extension can register custom tools, slash commands, and lifecycle hooks — and even intercept tool calls.

Looking for the high-level overview of skills, extensions, and plugins? See Extend CODA.

The easy way: let CODA write it

You don't have to learn the API to build an extension. CODA ships with a create-extension skill that scaffolds one for you — just describe what you want in plain language, no slash command needed:

I want an extension that adds a /deploy slash command which deploys the app to staging or production.

You can also trigger it explicitly with the /create-extension slash command. Either way, CODA generates the extension file, places it in the right folder, and explains how to use it. This is the recommended path for most people.

The rest of this page is a reference for when you want to understand what CODA generated, or hand-write and fine-tune an extension yourself — you don't need to read it to get started.

Anatomy of an extension

An extension is a TypeScript file that exports an activate (or default) function receiving the ExtensionAPI. It lives in .coda/extensions/ (project) or ~/.coda/extensions/ (global) — no configuration needed.

import { z, type ExtensionAPI, type AgentTool, type ToolContext } from "@globant/coda-core";

export default function activate(api: ExtensionAPI): void {
  // Register tools, commands, hooks
}

@globant/coda-core re-exports z (Zod) so your extension needs only one import source.

Where extensions load from

Extensions are auto-discovered, highest priority first:

Subdirectories with a package.json declaring coda.extensions, or an index.ts, are also discovered. To see what's loaded, run /extensions inside CODA.

Registering a tool

Tools are functions the agent can call. Use Zod for the parameter schema.

const myTool: AgentTool<MyParams, string> = {
  name: "my_tool",
  description: "Clear description of what the tool does and when to use it",
  parameters: z.object({
    query: z.string().describe("What to search for"),
    limit: z.number().int().positive().optional().describe("Max results"),
  }),
  label: "My Tool",
  execute: async (toolCallId, params, context: ToolContext) => {
    const cwd = context.cwd ?? process.cwd();
    // ... do the work ...
    return "result string returned to the agent";
  },
};

api.registerTool(myTool);

Inside execute, the ToolContext gives you what you need:

Description tips: lead with the category in CAPS, explain when the agent should pick this tool over alternatives, and include short parameter examples in the description.

Registering a slash command

Commands are invoked by the user as /name args.

api.registerCommand("deploy", {
  description: "Deploy the application to staging or production",
  getArgumentCompletions: (prefix) => {
    const options = [
      { value: "staging", label: "staging — deploy to staging" },
      { value: "production", label: "production — deploy to production" },
    ];
    const p = prefix.trim().toLowerCase();
    return p ? options.filter((o) => o.value.startsWith(p)) : options;
  },
  handler: async (args, ctx) => {
    if (!args.trim()) {
      ctx.addMessage?.("system", "Usage: /deploy [staging|production]");
      return;
    }
    await ctx.sendMessage?.(`Deploy to ${args.trim()}`);
  },
});

The handler context (ExtensionCommandContext) lets you drive the session:

Reserved command names — extensions can't override these built-ins:

model, models, clear, compact, exit, help, mcp, providers, settings,
skills, agents, extensions, plugin, plugins, reload-plugins,
init, timeline, rewind, checkpoint-status

Subscribing to lifecycle hooks

Hooks let you react to (or modify) what CODA does at key moments.

api.on("session_start", async ({ sessionId }) => {
  console.error("Session started:", sessionId);
});

api.on("context", async (context) => {
  // Mutate in place before each LLM call
  context.systemPrompt += "\n\n## My custom instructions\n...";
});

Intercepting tool calls

Use the tool_call hook to block dangerous commands or rewrite inputs before they run:

api.on("tool_call", async ({ toolName, input }) => {
  if (toolName === "bash" && input.command?.includes("rm -rf /")) {
    return { deny: true, reason: "Blocked destructive command" };
  }
});

See also

• Extend CODA — when to use skills vs extensions vs plugins.
• Tools Reference — the built-in tools your extension sits alongside.

Plugins

A plugin is a versioned, installable package that bundles CODA add-ons together behind a single manifest. Where a project extension is an ad-hoc TypeScript file you drop into .coda/extensions/, a plugin is a redistributable unit with a name, a version, and a source you can share across teams — installed once and tracked in a registry.

A single plugin can ship any combination of skills, agents, MCP servers, extensions, and hooks. That makes plugins the right choice when you want to package and distribute a reusable CODA integration, rather than wire each piece up by hand in every project.

Plugins vs. extensions

Both extend CODA, but they suit different needs:

For writing the TypeScript side, see Writing Extensions. This page covers installing and managing plugins.

Install a plugin

The most flexible way to install is the coda plugin install command in a terminal, which accepts several source types:

coda plugin install <source>

Useful flags: --scope project also pins the plugin in the nearest .coda/plugins.json (default is global, your user registry only); --name <folder> selects a subfolder when a git repo holds several plugins; --copy copies a local plugin instead of symlinking it.

You can also open the plugin manager inside a session:

/plugin

From the overlay you can browse, install, enable, disable, and manage marketplaces. Note that the in-session /plugin install accepts absolute local paths only — for npm, git, or marketplace sources, use coda plugin install in a terminal.

After installing, enabling, or disabling a plugin, run /reload-plugins or restart CODA so the change takes effect.

Manage installed plugins

These work both as coda plugin <cmd> in a terminal and as /plugin <cmd> inside a session:

• list — show installed plugins with their version and enabled state.
• info <name> — show details for one plugin.
• enable <name> / disable <name> — turn a plugin on or off without removing it.
• remove <name> (alias uninstall) — uninstall a plugin.

Where plugins are registered

CODA tracks plugins in two registries:

• User registry — ~/.coda/plugins.json. The source of truth: where each plugin is installed and whether it is enabled. Installing with the default global scope writes here.
• Project registry — the nearest .coda/plugins.json, found by walking up from your working directory. It declares which plugins apply to a given checkout. Commit it so teammates load the same set.

A plugin loads only when it is present and enabled in the user registry and its name is enabled in either registry. If a project lists a plugin that isn't installed, CODA warns you and points you to coda plugin install.

Marketplaces

A marketplace is a named catalog of plugins. Register one, then install any plugin it lists by name.

coda marketplace install <source>

The source can be a git repo URL, a local .zip, a directory containing a marketplace catalog, or a path to a marketplace.json file. Manage registered marketplaces with coda plugin marketplace list and coda plugin marketplace remove <id>, or from the /plugin overlay under Manage Marketplaces.

Once a marketplace is registered, install from it with the name@marketplace-id form:

coda plugin install my-plugin@acme

Authoring a plugin

A plugin is a directory with a manifest at .coda-plugin/plugin.json. The manifest declares the plugin's name and points at the assets it ships (as relative paths). Only name is required:

{
  "name": "context7",
  "displayName": "Context7 Docs",
  "version": "1.2.0",
  "description": "Fetches up-to-date library docs into the session context.",
  "skills": "skills",
  "agents": "agents",
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": { "DEFAULT_MIN_TOKENS": "10000" }
    }
  }
}

A matching directory layout:

my-context7-plugin/
  .coda-plugin/
    plugin.json
  skills/
    SKILL.md
  agents/
    context-fetcher.md

Key manifest fields: name (required, kebab-case), displayName, version, description, skills, agents, extensions, hooks, and mcpServers. The asset fields take a relative directory path (or list of paths). The formats are the same as elsewhere in CODA — see Skills, Agents, and Writing Extensions for the underlying file formats, which plugins reuse rather than redefine.

Bundled skills are namespaced as plugin-name:skill-name (from the skill's own name in its frontmatter). If a project already defines a skill with the same name, the project skill wins and the plugin's is skipped.

Compatibility with other ecosystems

CODA also reads plugin manifests authored for other tools. Manifests at .claude-plugin/plugin.json (Claude Code) and .cursor-plugin/plugin.json (Cursor) are accepted: recognized fields are used and unknown ones are ignored. Hook path placeholders like $CLAUDE_PLUGIN_ROOT and $CURSOR_PLUGIN_ROOT are rewritten automatically. A few foreign-only fields are skipped with a warning — Cursor rules (.mdc files) and Claude Code lspServers are not supported.

Hooks

Hooks let you run your own shell command or scripts at specific events in a CODA session — before a tool runs, after a file is written, when a session starts, and more. Use them to enforce policies (block dangerous commands), inject context (activate a virtualenv), run linters after edits, log activity, or notify an external system — all without touching CODA's source.

You configure hooks in config.json; there's nothing to install. CODA's hooks are compatible with Claude Code hooks — the same event names, the same JSON input/output contract, and the same hooks/hooks.json plugin convention all work here.

Hooks vs. extension hooks. This page is about config-based hooks you declare in JSON. That's different from the code-based api.on(...) hooks you write inside a TypeScript extension — those are for building integrations in code. If you just want to run a script at a lifecycle point, you're in the right place.

Quick start

Let's use hooks to compute some statistics on skill usage:

1. Navigate to the /hooks command and browse the hook events available in the application (each row shows how many hooks you've configured for that event).
2. Choose an event you want to "hook" into, for example PostToolUse and hit enter. This will allow you to perform actions after a tool is called.
3. Describe to the agent which action you want to take place after the tool was called. For example, "check if the skills tool was called and record the name of the skill called; track this in a file called .coda/skills-stats.txt"
4. Now use /reload-hooks to make it available in the session, or exit and re-enter the application.
5. Ask the agent to read a skill. Depending on how the script was written you should see a line being added to the skills-stats.txt file.

Where hooks are configured

Hooks are merged from three sources, highest priority first. When the same hook (same event + matcher + command/url) appears in more than one source, only the highest-priority copy runs.

To turn everything off (useful in CI), set "disableAllHooks": true at the top level of your config.

Hook events

Each event fires at a specific point in the session. The matcher on tool events is tested against the tool name (bash, write, edit, read, glob, grep, …) and is case-insensitive, so Claude Code's capitalized names like "Bash" also match. Omit the matcher (or use "*") to match everything. A matcher can be a pipe list ("write|edit") or a regex ("^mcp__.*").

Setting up a hook manually

For most users, we recommend using the agent (via the create-hook skill) to create a first version of a hook. However, in order to explain how the process works here is one example:

Add a hooks key to ~/.coda/config.json (applies everywhere) or <project>/.coda/config.json (this project only). This example logs every Bash command before it runs:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'About to run a Bash command' >> ~/.coda/hooks.log"
          }
        ]
      }
    ]
  }
}

Restart CODA — or run /reload-hooks inside a session — for the change to take effect. Use /hooks to browse every event and /hooks list to see what you've configured.

Common use cases

Block a dangerous command. A PreToolUse hook can stop a tool call. Exit with code 2 and CODA refuses the command, showing your message to the model:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [{ "type": "command", "command": ".coda/hooks/no-rm.sh" }]
      }
    ]
  }
}

#!/bin/bash
# .coda/hooks/no-rm.sh — read the tool input from stdin, block rm -rf
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
if echo "$COMMAND" | grep -qE '\brm\b.*-rf'; then
  echo "Blocked: rm -rf is not allowed" >&2
  exit 2
fi

Auto-format after every edit. A PostToolUse hook matching write|edit runs your formatter on the file that just changed:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.tool_input.file_path // empty'); [ -n \"$FILE\" ] && npx prettier --write \"$FILE\" 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}

Activate a virtualenv for the session. A SessionStart hook can write environment variables to the file at $CODA_ENV_FILE; CODA sources it before every Bash command for the rest of the session:

#!/bin/bash
# SessionStart hook
[ -f ".venv/bin/activate" ] && source .venv/bin/activate
echo "export VIRTUAL_ENV=\"$VIRTUAL_ENV\"" >> "$CODA_ENV_FILE"
echo "export PATH=\"$PATH\"" >> "$CODA_ENV_FILE"

Call a webhook without slowing things down. An HTTP hook marked async fires and is not waited on:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.example.com/coda-prompt",
            "headers": { "Authorization": "$WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 3,
            "async": true
          }
        ]
      }
    ]
  }
}

How a hook is defined

Each event maps to a list of matcher groups; each group has a matcher and a list of hooks. A hook is either a command (shell) or an http call.

Command hooks

HTTP hooks

What a hook receives and can return

Every hook gets a JSON object on stdin (or as the HTTP body) with session_id, cwd, hook_event_name, and event-specific fields — for tool events that includes tool_name and tool_input. Read it with jq as in the examples above.

To just observe, exit 0 and print nothing. To block (on events that allow it), exit 2 and write your reason to stderr. For richer control, print a JSON object to stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",         // allow | deny | ask
    "permissionDecisionReason": "Policy: no force-push",
    "updatedInput": { "command": "git status" }  // rewrite the tool args
  }
}

PostToolUse hooks can instead return additionalContext (appended to the tool result as [Hook] …) or updatedToolOutput (replaces it). UserPromptSubmit hooks can return updatedPrompt to rewrite your message. Any hook can return { "continue": false, "stopReason": "…" } to stop the agent entirely.

Manage hooks from a session

Good to know

• Matching hooks run in parallel. If two hooks change the same thing (e.g. both rewrite the prompt), the result is last-write-wins and the order isn't guaranteed.
• Blocking fails closed. A synchronous hook that times out or errors with exit code 2 blocks the operation. Commands that can't be launched at all (not found / not executable) are treated as non-blocking warnings instead.
• Output is capped at 10,000 characters per hook (stdout and stderr each); extra output is silently truncated.
• $CODA_ENV_FILE is for bash/WSL, not PowerShell hooks.
• Plugin hooks run automatically once a plugin is installed — there's no separate trust prompt, so review a plugin's hooks before installing it.
• PostToolUse can't undo a tool. Blocking there flags the result as an error to the model; it doesn't roll back the action. To prevent an action, use PreToolUse.

See also

• Extensions — code-based api.on(...) hooks for building integrations in TypeScript.
• Permissions & Approvals — how CODA gates risky operations, which hooks can reinforce.
• Plugins — bundle hooks (and more) for your team.

Workflows

A workflow is a deterministic script that orchestrates multiple agents for you — fanning work out in parallel, running multi-stage pipelines, looping until a budget or count is reached, and synthesizing the results. Where a single agent handles one task, a workflow coordinates many, with the shape of the work decided at runtime.

Use a workflow when one agent (or a few inline steps) won't cover the job well — for example a repo-wide audit, reviewing every file in a changeset, or any sweep where coverage and confidence matter more than speed.

Workflows are opt-in and token-expensive — they can spin up many agent runs. Reach for one when the scale clearly warrants orchestration or when you've asked for thoroughness; otherwise a single agent is cheaper and faster.

Create a workflow

You don't write the script by hand. Ask CODA to build one and it delegates to the built-in create-workflow agent, which authors the workflow module and saves it for you:

Create a workflow to do an independent per-principle SOLID audit — one reviewer per principle (SRP/OCP/LSP/ISP/DIP), each finding adversarially verified, synthesized into per-principle verdicts + a prioritized fix list. Write an artifact with your findings.

The create-workflow agent writes the file but doesn't run it. The first time you run a freshly authored workflow, CODA asks you to confirm — you can approve it, view the generated script, or decline. After that first confirmation, running it again goes straight to the background.

Run a workflow

You don't need a special command. Just ask in plain language — if a matching workflow exists, CODA runs it. Using the SOLID audit from the example above:

Run the SOLID audit workflow on my codebase

A few things to know about how runs behave:

• They run in the background. CODA shows a "running" notice and keeps the session responsive. You get the outcome on a later turn, when CODA posts a short overview of what the workflow produced (including links to any artifacts it wrote).
• CODA infers the inputs. It reads the arguments a workflow needs from your request, and only asks you when something required can't be determined.
• Track progress anytime from the dashboard (below).

Watch and stop runs with /workflows

Open the workflow dashboard to see live progress as a tree of phases and agent cards, plus the history of past runs:

/workflows

To stop a run:

• Command: /workflows stop <runId> stops that run; /workflows stop (no id) stops all in-flight runs for the session.
• Dashboard: press c on a running entry to cancel it.

Where workflows live

Workflows are discovered automatically from your project and your user-global config, so anything committed to the repo is available to the whole team:

• <project>/.coda/workflows/ — project-specific (commit these to share them).
• ~/.coda/workflows/ — personal, available in every project.
• Plugins may also bundle their own workflows.

For Claude Code compatibility, CODA also discovers workflows under .claude/workflows/.

Good to know

• No enable/disable setting. Unlike skills or MCP servers, there's no toggle — a workflow is available as soon as its file is discovered.
• Background by design. Because runs are non-blocking and report back on a later turn, you can keep working (or start another run) while one is in flight.
• Built on agents. Every step a workflow runs is a normal agent run, so the same model, concurrency, and approval rules apply.

Authoring by hand (advanced)

Most people never write a workflow directly — the create-workflow agent does it for you. But if you want to read or tweak what it produced, here's the shape.

A workflow is a TypeScript file (.ts, .mts, .js, or .mjs) that exports a meta object and a run function:

export const meta = {
  name: "solid-audit",
  description: "Independent per-principle SOLID audit with verification.",
  whenToUse: "When the user asks for a thorough, repo-wide SOLID review.",
  argsHint: "{ scope?: string }",
};

export async function run(ctx) {
  ctx.phase("Audit");
  const findings = await ctx.agent("Review SRP in the target scope", {
    schema: /* optional Zod/JSON schema for typed output */,
  });
  await ctx.writeArtifact("report.md", findings);
  return { done: true };
}

• meta describes the workflow. whenToUse helps CODA decide when to suggest it; argsHint tells CODA what arguments to infer from your request.
• ctx is how a workflow orchestrates work. The main helpers: ctx.agent(prompt, opts) to run a sub-agent (with an optional schema for typed output), ctx.parallel(...) and ctx.pipeline(...) to fan work out, ctx.phase(title) and ctx.log(msg) for progress, ctx.writeArtifact(name, content) to save a result file, and ctx.args/ctx.budget for inputs and spend.

You don't need to memorize the full API — this is just enough to recognize and adjust a generated workflow. Ask CODA if you want it to explain or extend one.

See also

• Agents — the single-task delegation that workflows orchestrate.
• Extend CODA — skills, extensions, plugins, and MCP.
• Tools Reference — the run_agent family and the rest of CODA's tools.

Commands & Flags

Reference for the slash commands available in the interactive TUI, plus the shell flags you pass when launching CODA from the terminal. Type /help inside CODA at any time to see the current list (extensions may add more).

Session management

Files and changes

Configuration

Tools and extensions

Context

Shell flags (run before opening CODA)

Headless provider selection

Use these flags to select a provider without going through the setup wizard — useful for scripts and CI.

Shell subcommands

Besides launching a session, coda has a few management subcommands you run directly from the shell.

Configuration Reference

Reference for the most common configuration options. For how to set these up in practice, see Configuration. Most of these can be changed from the UI — you rarely need to edit the files by hand.

Config file locations

Values in config files can reference environment variables with ${VAR} (or ${VAR:-default}). Those variables come from your shell, from ~/.coda/.secrets, or from a project .env — which is how API keys stay out of the committed config.

Active provider and model

The provider you use is selected through profiles. A profile bundles a provider, an instance, and how to authenticate; you switch between them with /switch-profile.

Deprecated: top-level provider. Older configs used a single top-level provider key. It still works for backward compatibility, but activeProfile + profiles is the current mechanism — and it's what the setup wizard and /switch-profile write. You normally never edit these by hand.

providers map

Any provider entry can also pin per-tier models with fastModel, smartModel, and deepModel.

bash

compaction

tools

Controls the built-in search tools.

webSearch

Used by the web_search tool when your provider doesn't supply its own search.

vision

Used by the examine_images tool.

reasoning

fallback

Switch to a backup provider if the primary one errors.

session

hooks

Lifecycle hooks are configured under a top-level hooks key — see Hooks for the full event list and syntax.

Other common settings

This isn't every option — advanced blocks like telemetry, logging (levels and redaction), errorHandling, and checkpoints disk caps also exist but are rarely edited by hand. Settings cascade in priority order: CLI flags override project config, which overrides your global config.

Environment variables

Tools Reference

Tools are the capabilities CODA's agent can use to actually do work: read a file, run a shell command, search the codebase, call an MCP server, load a skill, or delegate to a sub-agent. You don't type tool names yourself — CODA picks the right tool for each task. This page maps the built-in tools and what you can configure about them.

How tools show up

CODA builds a tool registry for each session. Which tools are available depends on a few things:

• Provider — some tools (like web search or vision) require a Glob.AI profile.
• MCP configuration — connected servers add their own tools.
• Agents — delegation tools appear only when agents are enabled.
• Extensions and plugins — these can register additional tools.

Some tools pause for approval before doing something risky — see Permissions & Approvals. Headless runs use a stricter set: the ask_user tool isn't available, and bash defaults to a higher auto-approval tier.

To limit which tools a single run may use, pass coda --tools … (see Commands & Flags).

Built-in tools

Extensions and plugins can register more tools the same way the core registers these built-ins.

What you can configure

Tool behavior is configured in a few different places — some from the /settings panel, some from your config files, and some from dedicated managers. The highlights:

Tools inside agent runs

When a delegated agent run executes, it uses a trimmed tool set. The nested-delegation and interactive tools — run_agent, wait_agents, cancel_agent, workflow, and ask_user — aren't available in the child session, so delegated work can't recursively spawn the same machinery or stop to ask a question. Everyday tools like read, write, edit, bash, grep, and mcp_execute are available, so a sub-agent can still do real work and use your connected MCP servers.

See also

• How CODA Works — tools, memory, and the agent loop in context.
• Permissions & Approvals — when and why tools pause to ask.
• Extend CODA — adding tools via MCP, extensions, and plugins.

Reasoning Effort

Some models can reason before they answer — spending extra internal "thinking" on a problem before writing the final response. Effort control lets you dial how much of that reasoning a model does, trading speed for depth. Turn it up for hard refactors, tricky debugging, or architectural questions; keep it low for quick, routine edits.

Set the effort level

Use the /effort slash command in a session:

/effort high

The available levels, from least to most reasoning, are low, medium, high, xhigh, and max. Not every model supports every level — max in particular is reserved for the most capable models.

Run /effort with no level to open an inline selector showing only the levels the current model supports:

/effort

You can also set effort from the model picker (/switch-model), which includes an effort selector for reasoning-capable models — and lets you save it as your default for new sessions.

Make it your default

To apply a level automatically in every session, add a reasoning block to your CODA config (~/.coda/config.json for all projects, or <project>/.coda/config.json for one):

{
  "reasoning": {
    "enabled": true,
    "effort": "medium"
  }
}

enabled must be true for reasoning to be sent to the model; effort is the default level. Saving an effort from the model picker writes this block for you.

Models that don't support it

Effort only applies to reasoning-capable models. If the active model doesn't support it, the setting is silently ignored — no error, the session just runs normally — and /effort tells you the current model can't configure effort. If you carry a level over to a model that doesn't accept it, CODA adjusts it to a supported one automatically.

Showing or hiding the thinking

When a model is reasoning, its thinking can appear in the transcript. Press Ctrl+O to toggle that thinking visible or hidden. This is a display toggle only — it doesn't change the effort level or turn reasoning on or off. (Some models reason internally without exposing their thinking, so there may be nothing to show even with effort set.)

Keyboard Shortcuts

These shortcuts work inside the interactive TUI. Type ? at any time to open the shortcuts overlay, or /help for the full command list (extensions may add more).

Global

In the chat input

Tip — attach screenshots. Paste a path to an image file (or paste the image itself where your terminal supports it) and CODA picks it up as visual context — it shows a short [Image N] marker so you know it'll be sent. Useful for sharing a screenshot of an error or a UI mockup.

During a turn

Transcript navigation

Model switching

Favorite models are a shortlist you can flip between without opening the picker. To build it, open the model picker with /switch-model (or /sm) and press Space on any model to star it. Then Shift+Tab cycles through your starred models in chat. (Available with Glob.AI providers.)

FAQ

Common questions, organized by what you're trying to do.

Getting started

How do I check which version I'm running?

coda --version

On Windows, after installing I get "coda: The term 'coda' is not recognized...". What's wrong?

Nothing — this is expected on Windows right after a fresh install. PowerShell hasn't picked up the updated PATH yet. Close and reopen your terminal (or open a new tab) and try again. See Installation → Troubleshooting for details.

How do I add or change a provider?

From your terminal (outside a session): coda --reconfigure. From inside an active session: /providers. Note that /providers changes require restarting CODA to take effect.

CODA opened and immediately shows a setup wizard. Is that normal?

Yes. The wizard appears automatically on first launch if no provider is configured. Follow the prompts to add your credentials. You can also trigger it manually at any time with coda --reconfigure.

How do I get help from inside CODA?

A few ways: type /help for the command list, press ? for the keyboard-shortcuts overlay, or just ask CODA in plain language ("how do I undo a change?"). When you ask about CODA itself, it automatically delegates to the built-in coda-help agent, which answers from the local user guide. See Agents for more.

Working with sessions

How do I pick up where I left off?

Use coda --lastsession to resume the most recent session. For a specific session, use coda --session-id <id> — when you exit, CODA prints the exact coda --session-id <id> command, ready to copy and paste. From inside CODA, browse sessions with /sessions.

What does the context percentage in the status bar mean?

It shows how full the current conversation context is. When it approaches 100%, CODA automatically compacts the session history. If you're seeing degraded quality near 100%, run /compact manually or start a /new session.

CODA seems to have "forgotten" something from earlier in the session. Why?

Automatic compaction condenses older messages into a summary to keep the session running. If you need full history for debugging, open /settings → Context Compaction to disable it or adjust when it kicks in.

Making changes

How do I undo what CODA just did?

Type /timeline (or /rewind, or press Esc twice) to see all snapshots from this session. Pick the checkpoint from before the message that caused the bad change: CODA restores your files to the state they had right before that message was processed. Requires Git 2.5.0+.

How do I stop CODA from asking me to approve every command?

Raise the bash approval level from /settings → Bash Tool Preferences. Levels go from safe to high — see Configuration for what each one auto-approves.

What is AGENTS.md and should I have one?

It's optional, but recommended — especially for shared projects. It's a Markdown file at your project root that CODA reads at the start of every session, where you document your coding conventions, how to run tests, what files not to touch, etc. Generate one with /init (or write it by hand), customize it, and commit it to Git so the whole team benefits.

Extensions and tools

How do I connect an MCP server?

Open the /mcp manager inside CODA and add the server — paste its JSON or import it from a file. From the same place you can check its status, view its tools, and enable or disable it. See MCP Servers for details.

How do I create a skill?

Create a .md file with YAML frontmatter (name and description are required) and place it in <project>/.coda/skills/ or ~/.coda/skills/. CODA picks it up automatically when your request matches the skill's description — just ask in plain language. Each skill also gets a slash command (/skill-name) if you want to trigger it explicitly. See Skills for a complete example.

How do I create an extension?

The easiest way is to ask CODA: run /create-extension and describe what you want in plain language — the built-in create-extension skill scaffolds the TypeScript file and places it in the right folder for you. If you'd rather hand-write or fine-tune one, see Writing Extensions for the full API reference.

What are agents?

Agents are Markdown-defined profiles that CODA can use to delegate subtasks — like spawning a second CODA instance to explore one area of the codebase while the main session works on another. Just ask in plain language and CODA decides when to delegate automatically.

What's the difference between an agent and a workflow?

An agent handles one delegated task. A workflow orchestrates many agents — running them in parallel, in pipelines, or in loops — for jobs too big for a single agent, like a repo-wide audit. Ask CODA to build one (it uses the built-in create-workflow agent), run it by name in plain language, and monitor it with /workflows. See Workflows.

Glossary

Quick definitions for terms used throughout the docs.

Release History

This page tracks notable changes across CODA releases — new features, improvements, and bug fixes — grouped by month and version.

July 2026

CODA v1.0.0 — July 14, 2026

A complete, ground-up rebuild of the Coding Agent — faster, smarter, and designed around the way you actually work. Here's everything that's new.

Getting Started

• Easy Install: Get running with a single command — no Python and no manual setup required.
• OAuth Login: Sign in through your browser with your Globant credentials. Tokens are stored securely and refreshed automatically, so you authenticate once and stay signed in.

Ways to Run It

• Interactive Terminal UI: A brand-new terminal interface that explores your codebase, edits files, runs commands, and verifies its own work — with you in control at every step.
• Headless / Batch Mode: Run the agent non-interactively from scripts, CI/CD pipelines, or any automation. Feed it a prompt via flag, file, or stdin and get text or JSON output back — same agent, same tools, no UI required.
• Editor Integration (ACP): Full Agent Client Protocol (ACP) support for native third-party integrations. This lets you use editors like Zed and JetBrains IDEs, where edits appear as your editor's native diffs, commands run in its terminal, and approvals use its own permission prompts.

Core Capabilities

• Access All Frontier Models: Switch between Anthropic, OpenAI, Glob.AI, Azure, Google, Vertex, Groq, OpenRouter, and local models mid-session, without losing context.
• Provider Profiles: Save multiple provider setups and jump between them with /switch-profile. Keep separate accounts side by side and switch the active one without editing config by hand.
• Clipboard Image Paste: Paste an image straight from your clipboard into the prompt — no need to save a file first.
• Model Quality Tiers: Point agents and workflows at a fast, smart, or deep tier instead of hard-coding a model, and let CODA pick the right one for your active provider.
• Effort Control: Tune how much a model reasons — from quick answers to deep thinking — for supported models, without leaving your session.
• Checkpoints: Every prompt auto-snapshots your worktree. Rewind both your files and your chat history to any previous turn.
• Parallel Sub-agents: Delegate work to multiple agents that run in the background while you keep working on other tasks.
• Workflows: Structured multi-agent orchestration for complex tasks — fan out work in parallel, run multi-stage pipelines, and synthesize results, all from a single request.
• Message Queuing: Type and queue your next messages while CODA is still working — no need to wait for the current turn to finish.

Extend & Customize

• Extensions, Plugins & Marketplace: Create your own tools, slash commands, and hooks — or install existing ones. Compatible with the Claude Code ecosystem.
• Lifecycle Hooks: Run your own shell command or HTTP call at key moments — before a tool runs, after a file changes, on session start, and more. Enforce policies, block risky commands, inject context, or run linters, all from config.json. Claude Code-compatible.
• MCP Servers: Connect Model Context Protocol servers to give the agent access to external tools and data sources.
• Skills: Load reusable, Markdown-defined task templates that the agent can discover and invoke on demand.
• Memory: Global and project-specific memory that retains your preferences and context across sessions.

Under the Hood

• Turbo Search: Instant codebase search powered by ripgrep and fast-grep.