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 OS 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.

The instance in the link you followed can't be used. The commands below install Coda with its default setup.

These commands set up Coda to connect to , the Glob.AI OS instance named in the link you followed.

macOS & Linux

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

Windows (PowerShell 7) — restart your terminal after installing

irm 'https://docs.globant.ai/en/filedownload?5346,8' | 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). Both origin URLs and URLs ending in /v1 are accepted; CODA normalizes the endpoint paths automatically.
3. API key — your API key for that instance.

CODA creates a named profile in your config. The key is stored encrypted in the secure credential store (OS keyring when available, AES-256-GCM file otherwise) — never in plain text.

--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 encrypted using your OS keyring (falling back to AES-256-GCM file storage if the keyring is unavailable). This happens automatically — no extra setup required. Keys are never stored in plain text 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).

When a model is deprecated

If the model you're using is retired by the provider, CODA detects the error and handles it automatically:

• In the TUI: a model picker opens and blocks new prompts until you select a replacement. You can also run /switch-model to resolve it manually.
• In headless mode: the run exits with an error by default. Set CODA_MODEL_AUTOHEAL=1 to let CODA pick a replacement automatically and continue.

To map a specific retired model to a known replacement, add it to modelResilience.successorMap in your config:

{
  "modelResilience": {
    "successorMap": {
      "openai/gpt-4": "openai/gpt-4o"
    }
  }
}

To disable auto-healing for a specific profile (always ask, never auto-switch), add "strictPin": true to that profile entry.

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. If the session is idle, the switch takes effect immediately; if a turn is running, CODA saves it for the next launch. In the picker, press r to rename a profile label or d twice to delete the selected profile.

For switching the active project within a profile (when using Glob.AI OS 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 OS 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. When the current session is idle, the new profile takes effect immediately and the session keeps its conversation. If a turn is already running, CODA persists the selection for the next launch instead of changing the provider mid-turn.

The same picker also manages profiles:

• Press r to rename the selected profile's display label. The profile ID does not change, so references to it remain valid.
• Press d twice to confirm deletion; any other key cancels. Deleting the active profile clears the active selection instead of guessing a replacement. For API-key profiles, CODA also removes the credential when no other profile references it.

/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 OS OAuth profiles. It does not apply to API-key-only profiles (Corp), custom instances, or non-Glob.AI OS 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

Permission mode — controls how much CODA can do without asking you first. Press Ctrl+P in the TUI to cycle through the three modes:

• read-only — only reads; all writes, edits, and shell commands are denied.
• default — reads plus in-project edits; risky or out-of-project actions still ask. This is the recommended mode for everyday work.
• auto — reads, edits, and most shell commands run without prompting; only catastrophic actions are blocked.

For fine-grained control — always allow a specific command, always ask before a push, always deny rm -rf — see Permissions & Approvals.

Some settings can be adjusted from the settings panel (/settings inside CODA):

Bash Tool Preferences — pick which 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.

Autonomy — enable or disable /goal and /loop, choose the judge model, and set loop limits. Changes to the enabled setting apply to the current session immediately; no restart is required.

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 permission mode, which you cycle with Ctrl+P in the TUI:

See Permissions & Approvals for fine-grained allow/ask/deny rules, and Configuration for setting the mode 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 your global and project-root instructions at the start of every session, then loads more specific files from subdirectories as it reads files there. Use them to describe coding style, testing approach, which areas to avoid, and how to run 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 (API keys are stored in the encrypted credential store; other env vars go 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 OS 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 permission mode. Setting permissions.defaultMode to auto 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.

Layer instructions in a monorepo

CODA combines instructions at three levels:

1. Global — ~/.coda/AGENTS.md, applied to every project on your machine.
2. Project root — the instruction file at the directory where the session starts.
3. Subdirectories — when CODA reads a file, it walks from that file's directory toward the project root and loads instruction files it has not seen yet. The most specific directory is loaded first, and each file is loaded at most once per session.

At each directory, CODA uses the first available filename in this order: AGENTS.md, AGENT.md, then CLAUDE.md. The project-root and global files are part of the initial system instructions; subtree files are added only when relevant, so large monorepos do not load every package's conventions up front.

For example:

my-monorepo/
├── AGENTS.md                 # conventions for the whole repository
├── packages/
│   └── billing/
│       ├── AGENTS.md         # billing-specific rules
│       └── src/invoice.ts
└── services/
    └── API.md

A read of packages/billing/src/invoice.ts applies the root conventions plus packages/billing/AGENTS.md; unrelated package instructions remain unloaded. Put shared rules at the root and narrower rules beside the package or subsystem they govern.

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 tool calls are allowed, use permissions.allow, permissions.ask, and permissions.deny in config.json — see Permissions & Approvals.

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.

Permission modes

Every CODA session runs in one of three permission modes. The mode decides which actions are auto-approved, which pause to ask you, and which are refused outright.

default is the recommended mode for everyday work. It lets CODA do the routine things without interrupting you, while still pausing on anything that could cause real damage.

Switching modes

In the TUI: press Ctrl+P to cycle through read-only → default → auto. The current mode is shown in the status bar.

Ctrl+P is available once the conversation starts. To set the mode before that, use the config option below.

In config (applies to every new session):

// ~/.coda/config.json  or  <project>/.coda/config.json
{
  "permissions": {
    "defaultMode": "default"   // "read-only" | "default" | "auto"
  }
}

In headless mode:

# Equivalent to "auto" — approves everything it can
coda -p "Run the test suite" --auto-approve all

# Equivalent to "default" fail-closed — aborts if it hits something that would need approval
coda -p "Review the diff" --auto-approve none

Legacy aliases. Older configs may use bypassPermissions (→ auto), acceptEdits (→ default), or plan (→ read-only). These still work but are deprecated — use the new names going forward.

Fine-grained rules

Beyond the mode baseline, you can write explicit allow, ask, and deny rules that apply to specific tools or commands. Rules are evaluated before the mode baseline, and deny always wins.

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(git status)",       // always allow this exact command
      "Bash(git log:*)",        // allow any git log variant
      "File(src/**/*.ts)"       // allow edits to any .ts file under src/
    ],
    "ask": [
      "Bash(git push:*)"        // always ask before any git push
    ],
    "deny": [
      "Bash(rm:*)"              // never allow rm, regardless of mode
    ]
  }
}

Rule patterns follow the format Tool(pattern) where Tool is the tool name (Bash, File, WebFetch, etc.) and pattern is a glob or exact string.

A broad allow is a real grant — scope it tightly. Allowing a command that reaches another machine hands over that capability in full. In particular, allow Bash(ssh:*) grants arbitrary command execution on the remote host — CODA mediates only what runs locally and cannot police what happens on the far side of the connection. Prefer specific rules (Bash(ssh deploy@host:*)) over blanket ones.

When CODA asks to change the rules

CODA can propose a permanent rule change when an action is refused or repeatedly asks — for example, suggesting an allow rule for a command you keep approving. This propose-a-rule affordance is on by default. What happens next depends on the direction of the change:

• Tightening (adding a deny, lowering the mode) applies on its own. It only ever removes capability, so there is nothing to approve.
• Widening (an allow/ask rule, removing an existing rule, raising the mode) always asks you first — there is no mode, including auto, in which a widening applies by itself.

The approval prompt shows a summary the engine computes from the rule itself — what the rule would actually let CODA do, how broad it is, which config file it lands in, and warnings for risky shapes (unbounded grants, reaching outside your project, rules that apply in all projects). It also reminds you the change is permanent. You are approving the effect, not CODA's pitch for it.

A few limits worth knowing:

• You can always say no. Declining changes nothing; CODA carries on with the action still blocked.
• Headless runs never auto-approve a widening — with no one to ask, it is simply refused.
• A project can't grant itself more autonomy. A project-scoped request to raise the permission mode is rejected outright.
• The un-relaxable floor, managed policy, and CODA's own control-plane files stay protected — proposing can never reach them.

Every proposal — applied, declined, or refused — is recorded in the authorization log, marked as agent-proposed.

Turning it off:

{
  "permissions": {
    "proposePolicy": false   // opt this project (or user) out of rule proposals
  }
}

You can also disable it for a single run with CODA_PROPOSE_POLICY=0, and an administrator can turn it off fleet-wide with the managed disableProposePolicy key (which no local config can re-enable).

Bootstrapping rules with init-rules

The fastest way to set up permission rules for a project is the built-in init-rules skill. It walks you through the process interactively:

1. Explores the project — reads AGENTS.md, package.json, CI workflows, and your command history to understand what commands the project actually runs.
2. Proposes a rule set — suggests allow/ask/deny rules that match the project's real commands, and confirms risky ones with you before applying.
3. Picks the scope — project (.coda/config.json, shareable with teammates) or global (~/.coda/config.json).
4. Applies via propose_policy — the same sanctioned, approval-gated path used by the /permissions command.
5. Optionally enables the LLM safety-check layer — configures permissions.llmSafetyCheck in config.json (always with a mandatory approval prompt).

Invoke it with /init-rules or just ask: "set up my permissions" / "configure allow/deny rules for this project".

LLM-assisted safety check (auto mode)

In auto mode, commands that would otherwise require a human approval (the "residual ask" floor) can be reviewed by a lightweight model chain before the prompt is shown. If the model classifies the command as safe, the approval is relaxed to allow — if it's inconclusive or rejects it, the normal approval flow runs unchanged.

This is off by default. Enable it in config:

{
  "permissions": {
    "llmSafetyCheck": {
      "enabled": true,          // default false
      "models": ["openai/gpt-5.4-mini"],   // optional; uses a built-in list if omitted
      "nudgeThreshold": 10      // optional; prompts the user after N auto-approvals
    }
  }
}

Key guarantees:

• Only relaxes — never tightens. The LLM check can only upgrade an ask to allow; it never changes an allow or a deny.
• Only runs in auto mode. The check never fires in read-only or default mode.
• Falls back gracefully. If all models time out or fail, the original ask is shown — no silent allows.
• Only applies when you have user-authored rules. Sessions with no personal rules skip the check entirely.

The un-relaxable floor

Some actions are always denied, regardless of mode or rules. No configuration can override them:

• Catastrophic shell commands (rm -rf /, fork bombs, dd to a disk device, mkfs, PowerShell equivalents)
• Managed policy denies (set by your organization's administrator)

CODA's own config and secret files are handled separately — see Control-plane file protection below.

Even in auto mode, these are refused outright.

Control-plane file protection

CODA protects its own configuration directory (.coda/) in two tiers:

• Secret files (.env, rules.json, credential files) — hard-denied in all circumstances. No rule, mode, or approval can let CODA write to these.
• Authoring files (config.json, mcp.json, memory.md, agents.md, append_system.md, and the extensions/ folder) — require a mandatory approval prompt that explains exactly what file is changing and what it controls. This prompt cannot be pre-satisfied by a rule, mode, or session grant. In headless mode, authoring writes fail closed.

This means CODA can help you scaffold an extension or add an MCP server — but it always asks first with a clear explanation, and your secrets are never at risk.

How approvals work

When CODA hits an action that requires approval, 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.

Overwrite guard

In default mode, CODA also asks before overwriting a file it never read this session — even if the file is inside the project. This anti-clobber guard prevents silently stomping on work it hasn't seen.

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 all (the default) approves every action automatically so the run doesn't hang. This is the most important default to understand before running CODA unattended.
• --auto-approve none aborts on the first action that would need approval — since there's no one to answer, it stops with an error instead of waiting.
• The ask_user tool ends the run. If the agent tries to ask you a question, the batch run aborts with an error.

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.

Choosing the shell

CODA runs bash commands through a shell you can configure. 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. Set it from /settings → Bash Tool Preferences or via bash.shellMode in config.

The authorization engine parses and classifies each command in the dialect it actually runs in — POSIX/bash, PowerShell, or cmd — so a decision on one shell matches the equivalent command on another. A read-safe command (cat, ls, Get-Content, dir) is recognized as read-only in whichever dialect it runs, and a catastrophic form is refused across all of them.

Note that cmd is an authorization-only dialect: the engine will classify Windows cmd.exe commands, but you can't select cmd as a bash.shellMode for execution — the selectable modes are auto, bash, powershell, and wsl. If a command runs in a shell CODA can't recognize, it's treated as the unknown dialect and fails closed — the command is refused rather than allowed on an assumption.

Managed (organization) policy

Administrators can ship a managed policy that everyone inherits and that no local config can override:

• Extra deny rules that are final — a managed deny always wins.
• Managed ask rules that force a prompt for matching actions, regardless of your local config.
• A locked permission mode — e.g. disableAutoMode forbids auto (disableBypassMode is a legacy alias for the same lock).
• allowManagedMcpServersOnly — restrict which MCP servers are allowed at all.
• allowManagedRulesOnly — a lockdown that drops non-managed allow rules.
• requirePolicy — require a managed policy to be present before CODA will start.
• disableProposePolicy — turn off rule proposals entirely; it cannot be switched back on by your config or by CODA_PROPOSE_POLICY.

Managed rules sit above your personal and project config.

Where to set it

• From inside CODA: Ctrl+P to cycle modes; /settings → Bash Tool Preferences for shell mode.
• Per project: project-level config overrides your personal defaults — see Configuration.
• For a single run: the --auto-approve flag (see Commands & Flags).
• Fine-grained rules: permissions.allow, permissions.ask, permissions.deny in config.

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.
• Configuration Reference — full list of permissions.* keys.

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.

Configuring Agent Intelligence Levels

This section explains how to configure the intelligence levels (model quality tiers) of agents in CODA through the config.json file.

Where the config file lives

• Global: ~/.coda/config.json — applies to all projects
• Project: <project>/.coda/config.json — project-specific overrides
• TypeScript config: <project>/coda.config.ts — takes priority if present

Settings cascade, from highest to lowest priority:

CLI flags → project config → global config → built-in defaults

The three intelligence tiers

CODA uses three tier shortcuts that resolve to concrete models:

The agents block in config.json

The agent intelligence tiers are controlled via the agents block.

Tiers can be set in two places (provider-level wins over agent-level):

1. Provider-level (per profile): profiles.<id>.fastModel, profiles.<id>.smartModel, profiles.<id>.deepModel
2. Agent-level (global): agents.fastModel, agents.smartModel, agents.deepModel

Concrete example

// ~/.coda/config.json
{
  "activeProfile": "geai-oauth",
  "profiles": {
    "geai-oauth": {
      "provider": "glob-ai",
      "label": "Glob.AI OS (OAuth)",
      "instance": "saas-europe",
      "auth": { "method": "oauth" },
      "model": "anthropic/claude-opus-4-8",
      // Per-tier models scoped to this profile (win over the agents block)
      "fastModel":  "anthropic/claude-haiku-4-5",
      "smartModel": "anthropic/claude-sonnet-4-6",
      "deepModel":  "anthropic/claude-opus-4-8"
    }
  },

  // Global agent config (used unless a provider profile overrides a tier)
  "agents": {
    "enabled": true,
    "maxConcurrent": 6,
    // Global tier overrides — used by all agents unless overridden per profile
    "fastModel":  "anthropic/claude-haiku-4-5",
    "smartModel": "anthropic/claude-sonnet-4-6",
    "deepModel":  "anthropic/claude-opus-4-8",
    // Hide bundled or custom agents
    "disabledDefinitions": []
  }
}

Per-agent override

An individual agent can pin its own intelligence tier or an exact model in its definition file — a Markdown file with YAML frontmatter located in ~/.coda/agents/ or <project>/.coda/agents/.

---
name: my-agent
description: My specialized agent
model: "smart"                    # Use the "smart" tier defined in config.json
# OR pin an exact model:
# model: "anthropic/claude-opus-4-8"
---

Instructions for the agent...

Valid model values:

• A full model ID (e.g., "anthropic/claude-haiku-4-5", "anthropic/claude-sonnet-4-6")
• A tier shortcut: "fast", "smart", or "deep"
• Omit entirely to inherit the main session's model

Model resolution order

When an agent runs, the model is resolved in this order:

1. Agent definition's model field (if set in the .md file) — highest priority
2. Tier shortcut resolution — if the agent uses fast / smart / deep:
   • First check profiles.<activeProfile>.fastModel / etc. (provider-level)
   • Fall back to agents.fastModel / agents.smartModel / agents.deepModel (global config)
   • Fall back to the built-in default for the tier
3. Default — if nothing is set, the agent inherits the main session's model

Common use cases

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.

Tracking agent costs

Every agent run's token usage and cost is tracked separately from the main session. Use /usage to open the cost overlay — it shows a per-source breakdown: the main agent row, then each sub-agent run with its own input, output, and cache token counts and cost in USD.

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, you can connect external services, teach repeatable processes, or orchestrate 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.

You can also ask CODA in plain language. The built-in configure-mcp skill handles Git repository URLs, remote HTTP endpoints, and npm/pip packages at project or global scope:

Configure the MCP server from this Git repository for the current project.

The skill confirms ambiguous scope or transport details, merges into existing config instead of overwriting it, refuses to embed credentials directly, and reminds you to choose Reload MCP servers in /mcp after the update.

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 built-in skills including plan (gathers context and writes an implementation plan), create-extension (scaffolds an extension), create-skill (writes a new skill from a plain-language request), and configure-mcp (safely configures an MCP server from a Git URL, remote HTTP endpoint, or npm/pip package at project or global scope). 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.

Agent Plugins Specification v1.0.0

CODA supports the open Agent Plugins Specification v1.0.0 as a fourth plugin format. A plugin in this format is detected automatically when its root plugin.json carries the canonical $schema:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "version": "1.0.0"
}

What maps to what:

Environment variables available to MCP server args/env/cwd:

CODA provisions the PLUGIN_DATA directory on load and removes it on uninstall.

Backward compatibility: existing coda, claude-code, and cursor format plugins are unaffected. The agent-plugins format is only activated when the $schema field is present and matches the canonical URL.

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. When CODA is running through the CLI, the payload also includes cli_version, equal to the version printed by coda --version. Embedding hosts that do not provide a CLI version omit the field. Read the payload with jq as in the examples above.

Command hooks receive the same value through the authoritative CODA_VERSION environment variable. This makes it possible to attribute logs or branch version-specific integration behavior without parsing executable paths. HTTP hooks receive cli_version in the POST body.

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.

Tracking workflow costs

Each workflow run's token usage and cost is tracked per agent run spawned. Use /usage to open the cost overlay — it shows a Flows section listing every workflow-spawned run with its individual input, output, and cache token counts and cost in USD, separate from the main agent and any ad-hoc sub-agents.

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

Autonomous mode

The autonomy model is off by default. CODA does not enter /goal or /loop mode unless you explicitly invoke these commands.

TODO lists

Utilities

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.

coda configure

Creates or overwrites a provider profile without going through the interactive setup wizard. Useful for CI/CD pipelines, onboarding scripts, or any environment where interactive prompts are unavailable.

coda configure --provider <name> --profile-name <name> [flags]

Exit codes: 0 success · 1 profile already exists (use --force to overwrite) · 2 missing required flag or unknown provider.

Examples:

# Glob.AI OS profile
coda configure --provider glob-ai --instance clients --api-key "my-key" --profile-name work

# OpenAI-compatible provider
coda configure --provider openai-compat --base-url https://api.openai.com/v1 --api-key "sk-xxx" --profile-name openai

# Local Ollama (no API key needed)
coda configure --provider ollama --base-url http://localhost:11434 --profile-name local

# Overwrite an existing profile
coda configure --provider glob-ai --instance clients --api-key "rotated-key" --profile-name work --force

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 non-API-key secrets stay out of the committed config. API keys are stored in the encrypted credential store and injected automatically.

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.

permissions

Controls the permission mode and fine-grained allow/ask/deny rules. See Permissions & Approvals for the full explanation.

Managed (organization) policy adds its own allow/ask/deny rules plus lockdown keys that no local config can override: disableAutoMode (forbid auto; disableBypassMode is a legacy alias), allowManagedMcpServersOnly, allowManagedRulesOnly, requirePolicy (require a managed policy before startup), and disableProposePolicy. See Permissions & Approvals.

Note for existing users. If your config uses bash.autoApproveLevel, it still works but is deprecated. The new permissions.defaultMode replaces it. "low" → "default", "high" → "auto", "safe" → "read-only".

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

composer

Controls how messages you type while the agent is busy are handled.

skills

hooks

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

Other common settings

webfetch

Controls the web_fetch tool. See Tools Reference for the full parameter list.

modelResilience

Controls what happens when a model is deprecated or unavailable.

Per-profile: add "strictPin": true to a profile entry to disable auto-healing for that profile — CODA will always ask instead of switching automatically.

Headless: set the CODA_MODEL_AUTOHEAL=1 environment variable to allow automatic model replacement in batch runs (otherwise the run exits with an error when the model is unavailable).

errorHandling

logging

Log verbosity and redaction. See View & Share Logs for the viewer and export tooling.

telemetry

Optional OpenTelemetry (OTLP) export for traces and metrics. Off by default; typically set by ops teams.

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 OS 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:

web_fetch configuration

The web_fetch tool fetches a URL and returns its content as markdown (default), plain text, or raw HTML. It also supports saving the result directly to a file in .coda/docs via the savePath parameter — useful for large pages you want to store without spending tokens on the inline response.

web_fetch vs web_search: web_fetch retrieves the full content of a specific URL. web_search runs a search query and returns summarized results with citations. Use web_fetch when you have a URL; use web_search when you need to find something.

Main-agent only. web_fetch is not available inside delegated agent runs or workflows.

Config options (in config.json):

To disable web_fetch entirely: add "WebFetch" to permissions.deny in your config.

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 none, minimal, low, medium, high, xhigh, and max. Use none to turn reasoning off for the turn and minimal for the lightest possible thinking when you want speed with a small amount of deliberation. 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.

Effort follows the session

An effort selected for this session only is stored with that session. If you switch to another session and later return, CODA restores the session's chosen model and effort instead of replacing them with the current global defaults. Agents launched from the session inherit the same effort.

Set effort for one CLI run

Use --reasoning-effort to set a level for one invocation, including headless runs:

coda -p "Review this migration plan" --reasoning-effort high

The flag accepts none, minimal, low, medium, high, xhigh, or max (case-insensitive). It changes only the in-memory config for that process, is inherited by sub-agents, and is never written to your global or project config. An invalid level exits with a clear error. If the active model cannot honor a valid level, CODA warns and runs without applying that override rather than silently substituting another level.

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. /effort shows only the levels CODA knows the current model supports and reports when the model cannot configure effort. A per-run --reasoning-effort override that the model cannot honor produces a warning and is not applied; CODA does not silently replace it with another level.

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

Permissions

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 OS providers.)

FAQ

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

Getting started

Is CODA an upgrade to the Python version installed via Self Service / Company Portal?

No. CODA is a completely new Coding Agent and must be installed separately. See the Installation guide to get started.

How do I get started as a Glober?

Run:

coda --globant

This starts the onboarding flow. Once onboarding is complete, you can simply run coda for future sessions.

How do I check which version I'm running?

coda --version

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?

Switch to a more permissive mode. Press Ctrl+P in the TUI to cycle through read-only → default → auto. default is the recommended starting point — it auto-approves reads and in-project edits while still asking for risky commands. auto approves almost everything. See Permissions & Approvals for the full breakdown.

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.

Troubleshooting

Common errors and how to fix them.

Installation

Windows — "coda: The term 'coda' is not recognized..."

This is expected 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.

macOS / Linux — "coda: command not found"

Your shell may not have reloaded the updated PATH yet. Open a new terminal window, or reload your shell configuration:

# zsh (default on macOS)
source ~/.zshrc

# bash
source ~/.bashrc

Then try running coda again.

Authentication

"No organizations available. Contact your administrator."

This message appears during OAuth login and usually means one of two things:

You're using an API key from the "API Keys for Agentic Software Development" email. Those keys are for training/testing purposes only — they aren't associated with an organization or project and don't support OAuth. During onboarding, select:

Glob.AI OS → Clients → API Key

Then paste the API key from that email.

You're trying to log in to an instance you don't have access to. Check with your team lead or administrator to confirm which environment (Corp or Clients) your account is provisioned for.

HTTP 401 Unauthorized

[authentication] Error: HTTP 401: {"errors":[{"description":"Unauthorized","id":401}]}

This happens when you're authenticated against the Clients environment but using a Corp API key (or vice versa). The key and the environment don't match.

Fix: during onboarding (or by running coda --reconfigure), make sure you select the environment that matches your credentials:

• Corp API key → select Glob.AI OS → Corp
• Clients API key → select Glob.AI OS → Clients
• Globant account (OAuth) → select Glob.AI OS → Corp and log in with your Globant credentials

OAuth login doesn't work — "Unable to connect"

If you're on the Corp environment, it is only accessible while connected to the VPN. If you see a connection error:

1. Connect to the Globant VPN.
2. Retry the login flow.

If you don't have VPN access yet, request it through the standard VPN request process.

Usage limits

"Quota exceeded"

Your API key has reached its usage limit for the current period. Options:

• Switch to the free Globant model — available to all Globers, no quota.
• Request a higher limit — if your project has a defined budget, evaluate increasing the quota through the project's billing process. See the Glob.AI OS FAQs for details.

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 version.

CODA v1.4.0 — September 4, 2026

This release makes CODA easier to adapt to your workflow: profiles can be switched and managed without restarting, reasoning effort follows each session and can be set per headless run, monorepos gain layered instructions, MCP setup can be delegated to a built-in skill, and hooks can identify the running CLI version. It also includes reliability, security, and Windows fixes.

Profiles & Providers

• Switch profiles without restarting. /switch-profile now updates an idle active session immediately. If a turn is already running, the selected profile is saved for the next launch instead. → Configuration
• Rename and delete profiles from the picker. In /switch-profile, press r to rename the selected profile's display label, or press d twice to confirm deletion. Renaming keeps the profile ID unchanged. Deleting an active profile clears the active selection, and unused API-key credentials are cleaned up. → Configuration
• More resilient Glob.AI OS authentication. OAuth refreshes now propagate to model-catalog calls and newly launched sub-agents. File-based credential storage can restore the correct account after /project switches on systems without an OS keyring, and custom Glob.AI OS API-key profiles are classified correctly.
• Flexible Glob.AI OS base URLs. Custom instance URLs are normalized safely whether they include a trailing /v1 or not, preventing double-versioned or missing-version endpoint errors. → Connect a Provider

Reasoning & Automation

• Reasoning effort is session-scoped. A session keeps its chosen model and reasoning effort when you switch away and return. Sub-agents inherit the parent session's effort. → Reasoning Effort
• Per-run reasoning effort. Use --reasoning-effort with none, minimal, low, medium, high, xhigh, or max to set effort for one invocation, including headless runs, without changing config files. Unsupported values are reported rather than silently replaced. → Reasoning Effort
• Headless timeouts are authoritative. When you provide --timeout, that deadline now governs background-agent draining too; the internal fallback is used only when no caller timeout is supplied. → Automate with Batch Mode
• Autonomy settings apply immediately. Enabling or disabling /goal and /loop from /settings now affects the current session, including when the session is created lazily after the setting changes.

Project Instructions & Extensibility

• Layered instructions for monorepos. CODA loads global instructions and the project-root instruction file at startup, then loads matching instruction files from subdirectories when files under those directories are read. Each directory supports the fallback order AGENTS.md, AGENT.md, then CLAUDE.md. → Collaborate with Your Team
• Built-in configure-mcp skill. Ask CODA to configure an MCP server from a Git repository, remote HTTP endpoint, or npm/pip package at project or global scope. The skill performs non-destructive config updates and uses variable references instead of embedding secrets. → MCP Servers
• Hook version metadata. Every hook payload can include cli_version, and command hooks receive the same value as CODA_VERSION, making version-specific diagnostics and integrations straightforward. → Hooks
• @globant/coda-core is now runtime-agnostic. (Breaking change for direct core-library consumers.) Bun APIs are no longer hardcoded; consumers choose @globant/coda-core/runtime/bun or @globant/coda-core/runtime/node and pass the adapters explicitly at composition time. Node.js consumers must install better-sqlite3 and fast-glob as optional dependencies.

Improvements

• /reload-plugins no longer drops your session. Reloading plugins while a session is active now completes cleanly without redirecting you to the landing page.

Bug Fixes

• Cached token counts now display correctly. Cache read and write tokens were silently lost on every streaming turn (the mode the TUI always uses), causing the token and cost counters to show zero for cached usage. Both are now captured and displayed accurately.
• Windows shell output restored. PowerShell and WSL commands no longer return empty output because process detachment is now limited to platforms that support that behavior.
• Emergency-compaction history preserved. Messages produced after an emergency mid-turn compaction are no longer dropped from session history.
• Safer project roots. CODA refuses to initialize in OS system directories and shows a clear warning instead of failing later.
• Cleaner terminal behavior. Double-Esc opens Timeline only when a session exists, queued-work spinners remain visible, MCP path editing handles cursor movement and pasted Windows paths correctly, and draft input survives permission dialogs.
• Skill installs from a repo root use the repository name. When installing a skill from a GitHub repository whose root is the skill itself, the installed skill name is now taken from the repository name instead of a temporary directory name.
• Telemetry totals reconcile. Exported token metrics now match the CLI totals. The OTEL exporter uses DELTA temporality — update your collector or dashboard if it was configured for CUMULATIVE aggregation.
• Security hardening. Project-only profiles can no longer reuse global secret references, IPv4-mapped IPv6 URLs are checked against private-address restrictions, and file-backed credential deletion and token-expiry handling are corrected.

CODA v1.3.0 — August 20, 2026

This release builds on v1.2.0 with Auth 2.0, autonomous goal/loop mode, a built-in TODO tracker, LLM-assisted safety checks, the Agent Plugins Specification, Glob.AI OS telemetry, and a thorough round of reliability and security improvements.

Auth & Providers (Auth 2.0)

• Glob.AI OS Auth 2.0 — Zitadel + Platform Gateway. Onboarding for Glob.AI OS now uses Zitadel as the identity provider and routes inference through the Platform Gateway. The setup wizard guides you through instance selection (SaaS Europe, SaaS US, Corp, Clients) and OAuth browser login. Existing API-key profiles continue to work. → Connect a Provider
• Platform Gateway streaming. Tool-bearing requests to the Platform Gateway now stream responses token-by-token (like every other provider) instead of waiting for the full response. A learned fallback handles any regression automatically with no user-visible failure.
• OpenAI model family on Platform Gateway. Models such as gpt-5.4, gpt-5.4-mini, gpt-5.5, and gpt-5.6-* are now fully supported on Platform Gateway profiles. A wire-format bug that caused ~100% failure for those models has been fixed.
• web_search on Platform Gateway. Web search now works correctly on Glob.AI OS Platform Gateway profiles (previously degraded with a 404 because the wrong URL was used).
• GEAI OAuth auto-retry on 401. Idle sessions whose token expires server-side before the local stale-window triggers now automatically force-refresh OAuth and retry the turn once, so you no longer see unexpected "Unauthorized" errors after a break.

Autonomous Mode (/goal and /loop)

• /goal command. Set an objective and let CODA pursue it over multiple autonomous turns, pausing only when it needs input or reaches a decision point. Off by default — opt in by running /goal <objective>. Use /goal stop (or cancel) to end. → Commands & Flags
• /loop command. Repeat a prompt on a timed interval: /loop [interval] <prompt> [--max N]. Use /loop stop to end. The interval can be natural language ("every 5 minutes") or a cron expression. --max N caps total iterations. → Commands & Flags
• Autonomy settings panel. A new Autonomy screen in the Settings Picker (/settings) controls the master on/off for /goal and /loop, the goal-completion judge model, and the loop max duration — without editing config files by hand.
• Judge model. Each autonomous turn is evaluated by a lightweight judge that decides whether the goal is complete, needs clarification, or should continue — with full cost accounting for judge calls.

TODO Lists

• Task tracker in the TUI. When CODA creates a plan with a TODO list, it appears as a pinned footer showing each item with its live status. The list disappears automatically when the turn ends and reappears if CODA resumes mid-plan. → Commands & Flags
• /todo-lists command. Open a full-screen overlay to inspect the current turn's TODO plan and each item's progress at any point during a session.
• Queued messages appear below the TODO tracker. Messages typed while the agent is still running are now shown in a dedicated area below the TODO footer, keeping the layout predictable.

Permissions & Security

• init-rules skill — interactive permission bootstrap. A new built-in skill that walks you through setting up permission rules (allow/ask/deny) and permission mode for a project. It explores your repo, discovers real build/test commands, proposes a rule set that fits, and applies it via propose_policy — with optional LLM safety-check setup at the end. Invoke with /init-rules or "set up my permissions". → Bootstrapping rules with init-rules
• LLM-assisted safety check (auto mode). A lightweight model chain can pre-screen commands in auto mode — if the model classifies the command as safe, the approval is relaxed automatically. Off by default; enable with permissions.llmSafetyCheck.enabled: true. → Permissions & Approvals
• Control-plane authoring uses a mandatory approval prompt. When CODA wants to edit its own config files (config.json, mcp.json, extensions, etc.), it shows a mandatory, effect-explaining approval prompt that no rule or mode can pre-satisfy. CODA's own secrets (.env, rules.json, credential files) remain hard-denied in all circumstances. → Permissions & Approvals
• coda.config.ts is no longer executed. Project-level TypeScript config files were previously import()-ed on startup, which allowed arbitrary code execution when opening a cloned repository. Migration: move any coda.config.ts settings into .coda/config.json. Every setting has a JSON equivalent.
• Heredoc and here-string arguments treated correctly. Provably-literal heredoc and here-string bodies are now classified the same as -c inline arguments — fewer unnecessary approval prompts with no new auto-allows.

New Plugins Format

• Agent Plugins Specification v1.0.0. CODA now recognizes plugins authored for the open Agent Plugins Specification v1.0.0. A plugin.json carrying the canonical $schema is detected automatically and loads skills, MCP servers, and native CODA components (com.globant namespace). Existing plugin formats are unchanged. → Plugins

Telemetry (Glob.AI OS)

• Telemetry integration for Glob.AI OS. Traces and metrics can now be exported to your organization's Glob.AI OS gateway via OTLP. Enable with telemetry.enabled: true. Sensitive spans are redacted before export; a fault-isolation layer ensures a telemetry failure never impacts agent turns.
• Telemetry settings panel. A new Telemetry screen in the Settings Picker (/settings) lets you toggle and configure telemetry export level interactively — no config file editing required.
• otlpPort defaults to 443. The default OTLP port is now 443 (the standard HTTPS port used by the Platform Gateway) instead of 4318. Set telemetry.otlpPort explicitly if you point directly at a collector.

Reliability

• Stream idle timeout — configurable and smarter recovery. A per-chunk inactivity timeout (default 240 s, configurable via errorHandling.streamIdleTimeoutMs) detects wedged streaming connections. When the timeout fires during a large-file write, CODA now guides the model to "write in parts" and resets the retry counter on real progress — so large file generation no longer aborts after a few retries. → Configuration Reference
• Turn history preserved on interrupt. Pressing Esc mid-stream no longer loses partial assistant output or tool results. The partial turn is persisted and the next turn sees the full picture.
• Context window resolved from last-known-good catalog. If the live model catalog is temporarily unavailable, the correct context window is now resolved from the persisted snapshot instead of silently falling back to 128 k.
• Slash commands are now case-insensitive. /Permissions, /Help, and other mixed-case variants now dispatch to the correct built-in command.

Bug Fixes

• Fixed the "Thinking…" spinner being invisible during the first prompt on a cold-start session.
• Fixed the "Thinking…" spinner being hidden behind the TODO footer when a plan was active.
• Fixed coda-help falling back to model knowledge instead of local docs when a custom CODA_HOME was set.
• Fixed skills discovery (BFS deep scan) incorrectly skipping skills in certain directory structures.
• Fixed stream idle errors incorrectly aborting large-file generation tasks after a few retries.
• Fixed a context window mismatch when resuming a session while the model catalog was temporarily unavailable.
• Fixed tool calls with empty-string id or name (e.g. from GLM-4.6) bypassing the validity guard and producing a generic error instead of triggering the proper recovery/retry path.
• Fixed /sessions switch showing 128 k context window for models with a larger window (e.g. 1 M). The context bar now reflects the correct limit immediately after switching, and compaction triggers at the right point.

CODA v1.2.0 — August 10, 2026

This release is all about control: a brand-new permissions engine puts you in charge of exactly what CODA can do — with named modes, fine-grained rules, and encrypted credential storage — alongside new tools, lighter reasoning levels, and a round of CLI polish. Here's what's new.

Permissions & Security

• Permission modes. Three named modes replace the old bash approval levels: read-only (reads only), default (reads + in-project edits, recommended), and auto (reads, edits, and most commands). Press Ctrl+P in the TUI to cycle modes. Set permissions.defaultMode in config to make a mode the default for all sessions. → Permissions & Approvals
• Fine-grained allow/ask/deny rules. Write per-tool rules in permissions.allow, permissions.ask, and permissions.deny to override the mode baseline for specific commands or file patterns. Deny always wins. → Permissions & Approvals
• CODA can propose permission changes. When an action is refused or keeps asking, CODA can now propose a permanent rule change. A tightening (a new deny, a lower mode) applies on its own; a widening (an allow/ask rule, removing a rule, raising the mode) always asks you first and shows a summary of what the rule would actually let CODA do. On by default — opt out with permissions.proposePolicy: false, CODA_PROPOSE_POLICY=0 for one run, or the managed disableProposePolicy fleet-wide. → Permissions & Approvals
• propose_policy tool. The new built-in tool that carries those proposals; every proposal is recorded in the authorization log, marked as agent-proposed. → Tools Reference
• Cross-dialect command classification. The authorization engine now classifies commands in the dialect they actually run in — POSIX/bash, PowerShell, and cmd — so read-safe commands (cat, ls, Get-Content, dir) are recognized across shells and catastrophic forms are refused on all of them. This means fewer over-blocks with no new silent auto-allows. → Permissions & Approvals
• unknown shell dialect fails closed. Commands that run in a shell CODA can't classify are refused rather than allowed on an assumption. cmd is recognized for authorization only and can't be selected as a bash.shellMode. → Permissions & Approvals
• Managed lockdown keys. Organization policy can now set disableAutoMode (forbid auto; disableBypassMode is a legacy alias), allowManagedMcpServersOnly, allowManagedRulesOnly, requirePolicy (require a managed policy before startup), and disableProposePolicy — none of which a local config can override. Managed policy can also ship its own allow/ask/deny rules. → Permissions & Approvals
• permissions.additionalDirectories. List extra root directories that count as in-project, so edits under them are auto-approved in default mode instead of prompting as out-of-project. → Configuration Reference
• Encrypted API key storage. Provider API keys are now stored encrypted via the OS keyring (falling back to AES-256-GCM file storage). No configuration required — keys are never stored in plain text. → Connect a Provider

New Tools

• web_fetch tool. Fetch any URL and get the content back as markdown, plain text, or raw HTML. Pass savePath to write the result directly to .coda/docs instead of returning it inline — useful for large pages. Also fetches PDFs by URL. → Tools Reference

Reasoning

• Lighter reasoning levels. reasoning.effort (and /effort) now accept none and minimal in addition to low–max — turn reasoning off, or ask for the lightest possible thinking when you want speed with a touch of deliberation. → Reasoning Effort

CLI & UX

• /permissions command. Shows the permission rules currently in force and where each one comes from — config, managed policy, or session — along with the active permission mode. → Commands & Flags
• /copy command. Copies CODA's most recent response to the clipboard. Pass an optional index (/copy 2) to copy an earlier response. Complements Ctrl+Shift+C, which copies only the last code block. → Commands & Flags
• /usage command. Opens a full-screen cost overlay showing token usage and USD cost broken down by source: main agent, sub-agents, and workflow runs — each listed individually. → Commands & Flags
• Queue or steer while busy. Messages you type during a running turn can now be queued (held until the turn ends) or used to steer the current turn. Configure the default with composer.whileBusy.delivery and the queue/steer toggle with composer.queueSteer.*. → Configuration Reference
• Cost breakdown in sidebar. The sidebar now tracks cumulative session cost in real time. Click ▸ Details to expand a per-origin breakdown — Main (main agent), Agents (sub-agents), and Flows (workflow runs) — and ▾ Details to collapse it again.
• Active profile and session pinned to top of pickers. The currently active profile and session always appear at the top of their respective picker lists.
• Effective launch model shown in home banner. The home screen now displays the model that will actually be used for the session.
• Esc cancels marketplace add/install. You can now abort a plugin marketplace operation mid-flow with Esc.
• Cross-page ↑↓ navigation in Discover. Arrow keys now navigate across pages in the plugin and agent Discover lists.
• Markdown tables sized to content. Tables in CODA's responses are now sized to their content width instead of stretching to the full terminal width.

Reliability

• Model-sunset resilience. When a model is retired, CODA automatically detects the error and opens a model picker in the TUI (or exits with an error in headless, unless CODA_MODEL_AUTOHEAL=1 is set). Configure explicit successor mappings with modelResilience.successorMap. → Connect a Provider
• Streaming idle timeout. A per-chunk inactivity timeout (default 120 s, configurable via errorHandling.posture) detects wedged streaming connections and classifies them as recoverable errors for retry. → Configuration Reference
• Startup performance. Model catalog loading and git detection are now deferred off the first-frame render path — the TUI opens faster.

Bug Fixes

• Fixed isGitRepo incorrectly reporting true when run outside a git repository.
• Fixed a crash when using read with an offset parameter.
• Fixed --session-id being ignored when creating a new session from the CLI.
• Fixed a Windows crash on startup where the TUI could fail with "Failed to initialize OpenTUI render library: error code 126". The root cause was a race condition between the render library path setup and the first TUI render — now resolved.
• Fixed the CLI logo overlapping the version header on small terminals.

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 OS, 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.

Improvements

• Project picker rework. The /project picker shows name-first columns with abbreviated IDs, supports pagination, and correctly applies the project switch across all surfaces (model, footer, /auth-status). Switching from the home screen shows a toast and stays on the home screen.
• Home-screen provider block. The home screen shows the active provider, organization, and project between the input card and the command quickstart.
• Default vision model. The default model for examine_images is openai/gpt-5.4. Users who ran coda init before this release will need to update vision.model in ~/.coda/config.json manually.
• YAML literal block scalars in skill frontmatter. Skill and plugin frontmatter now correctly parses description: | (literal block scalar) in addition to description: > (folded block scalar).