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). If a saved sign-in session is too large for the Windows Credential Manager's size limit, CODA stores it in the same encrypted file instead. 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 — /goal and /loop are on by default, and one switch (autonomy.enabled) turns both off together. This panel also turns the goal-completion judge on or off and sets the /loop maximum duration. Choose the judge's model with /goal model or /loop model. Each command shows a token-spend warning every time you run it; pick "Continue and don't show this again" in that warning to silence it for that command. Changes apply to the current session immediately; no restart is required.

UI Theme — pick from six built-in themes: classic, modern, solarized, nord, high-contrast, or light.

Output Style — change how CODA formats its responses (without changing what it does) under Output Style. Pick one of nine built-in styles, such as concise, explanatory, learning, spartan, or visual, or choose default for no style. You can also add your own as Markdown files in .coda/output-styles/ or .agents/output-styles/ (project), or in the same folders under your home directory. If two styles share a name, the project one wins. List them anytime with coda list-output-styles.

Notifications — get a desktop notification, a terminal bell, or a custom command when CODA needs your input or finishes a turn. See Attention notifications below.

Keymap — remap built-in shortcuts (scrolling, sidebar toggle, favorite-model cycling, and more) in ~/.coda/keybindings.json.

See the full Configuration Reference for every available option.

Attention notifications

CODA can let you know when it needs you while you are working in another window. Notifications are off by default and only fire in the interactive TUI.

1. Turn them on. Add a notifications block to ~/.coda/config.json (all projects) or <project>/.coda/config.json (one project), then restart CODA:

{
  "notifications": {
    "enabled": true
  }
}

With just enabled: true, CODA sends a desktop notification (OSC 9) and rings the terminal bell. Desktop notifications appear in terminals that support OSC 9 — iTerm2, WezTerm, Ghostty, Kitty, and Windows Terminal. In other terminals the bell is the fallback (usually a sound or a flashing taskbar icon).

2. Know when it fires.

• An approval is waiting — a tool call needs your Y/N.
• CODA asks you a question.
• A turn finishes — only if it took at least 5 seconds, so short replies stay quiet. Turns you interrupt with Esc don't notify.
• A turn fails with an error CODA can't recover from.

3. Tune it (optional).

4. Send notifications somewhere else (optional). Set command to route them to Slack, a script, a speech tool, or a log. CODA runs the command through your system shell for each notification and writes a JSON payload to its standard input:

{
  "kind": "approval",
  "title": "CODA needs your approval",
  "message": "Approve bash?",
  "sessionId": "<session id>",
  "at": 1760620800000
}

kind is approval, question, complete, or error, and at is a Unix timestamp in milliseconds. For example, on macOS or Linux, "command": "cat >> ~/coda-notifications.log" appends every payload to a file. The command runs in the background: its output is ignored, and if it fails CODA carries on without telling you.

For every field, see Configuration Reference.

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

Commit after every turn

If you want a Git history of what CODA did, step by step, turn on auto-commit. After each turn that changes files, CODA commits exactly those files, so you can review or revert each step with plain Git. It is off by default. In headless runs (-p) CODA makes one commit when the run ends, instead of one per turn.

{
  "git": {
    "autoCommit": true,
    "autoCommitPrefix": "coda"
  }
}

Each commit message is the prefix plus the first line of your prompt, shortened to 60 characters: coda: add the billing model. CODA shows a one-line note with the commit hash and the number of files (in headless runs, it prints the note to stderr).

A few things worth knowing:

• It commits only what the turn changed, including new files and deletions. Nothing is pushed.
• It never commits secrets or CODA's own database. Files such as .env (and .env.local), *.pem, *.key, id_rsa-style keys, .netrc, and files named credentials or secrets are left out, as are coda.db and its backup and lock files. If a turn changed only files like these, nothing is committed.
• In the terminal UI, interrupted turns aren't committed. If you press Esc during a turn, CODA skips the commit.
• It needs a Git repository. Outside one, CODA reports that the commit was skipped.
• It is independent of checkpoints. Checkpoints are still your undo button; auto-commit adds history in your own repository. For the settings, see Configuration Reference.

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.

Plan, Review & Collaborate

Beyond the core edit loop, CODA has a set of commands for planning work before you touch any files, getting a second opinion from other models, and reviewing or committing changes the way your team would.

Read-only planning with /plan

/plan <goal> switches the session to read-only and has CODA investigate the codebase without writing anything. When the turn ends, it saves a Markdown plan to .coda/plans/<timestamp>-<slug>.md with Context, Steps, Acceptance (a checklist), and Risks sections.

Review or edit the plan file like any other document. When you're happy with it:

/plan approve

This restores your previous permission mode and runs the plan as a /goal — CODA works through the steps autonomously until every acceptance item is checked off. Pass --auto to force auto mode for the implementation phase regardless of what mode you started from.

Ask several models at once with /council

/council <question> sends the same question to 2–5 models in parallel, each streaming in its own column, then has your active model synthesize a recommendation.

/council What's the better approach here: optimistic locking or a queue?
/council --models anthropic/claude-opus-4-8,openai/gpt-5.4 Which refactor is safer?

• Without --models, CODA uses the models you've starred as favorites in the model picker (adding your current model if you have fewer than two favorites).
• If there aren't enough favorites and you didn't pass --models, a member picker opens — press Space to mark members, Enter to run.
• The synthesis compares the answers in a few lines and recommends one (or merges them), ending with PICK: <n>.
• /council use <n|synthesis> continues the conversation using the answer you pick. /council show re-opens the last result.

/compare is an exact alias for /council.

Side questions with /btw

Sometimes you want a quick answer without derailing the main session's context.

/btw what does this error code usually mean?

In the interactive TUI, /btw hands the question to a small read-only helper agent. It sees the last few messages as context and can search the web, read files, and run read-only shell commands, so a question like "how did that library change in the last release?" gets looked up instead of guessed. The exchange never joins the session history, so it can't distort what the agent remembers about the task. The answer streams in a side panel next to the transcript. /btw show reopens the panel, /btw close dismisses it. /side is an exact alias.

Review a PR, branch, or diff with coda review (experimental)

Experimental. coda review and coda github install are experimental: their flags, output, and generated workflow may change in future releases.

coda review --uncommitted        # the default when you pass no target
coda review --base <ref>         # your working tree against a ref, such as main
coda review --commit <sha>       # one commit
coda review --branch <name>      # a branch (against --base, or the repo's main branch)
coda review --pr <number|url>    # a GitHub pull request

Pick one target. They are mutually exclusive, except that --base can accompany --branch. A PR's diff always comes from the PR itself, so --base is not accepted with --pr.

Findings are scored 🔴 critical, 🟠 high, 🟡 medium, or 🟢 low, and the full report is written to .coda/reviews/<target>/review-<n>.md on every run.

It can post on GitHub. With --pr, coda review posts its findings on the pull request by default. Pass --no-post to keep them local. With --branch it posts only when the branch already has a PR; --post forces it.

It can fail your CI. --fail-on <level> makes the command exit with an error when a finding is at least that severe. The default is medium, so a medium, high, or critical finding already fails the run. Use --fail-on critical to relax it or --fail-on none to never fail.

Other options:

Your own checks. Put one Markdown file per rule in .coda/checks/, and coda review runs each of them against the diff.

By default, coda review prints a single status line that updates in place; pass --verbose to see one line per tool call instead.

coda github install (experimental)

Wires coda review into your repository as a GitHub Actions workflow:

coda github install [--model <provider/model>] [--fail-on low|medium|high|none] [--mention /coda] [--allow-any-commenter] [--force]

This writes .github/workflows/coda.yml with two jobs: one that reviews every pull request automatically, and one that runs coda -p "<comment>" whenever someone comments /coda ... (or your chosen mention) on an issue or PR — restricted to repo owners/members/collaborators unless you pass --allow-any-commenter. --force overwrites an existing workflow file. Credentials are read from the repo's CODA_API_KEY (and optional CODA_BASE_URL) secrets.

Governed commits with /commit

/commit
/commit fix: correct the off-by-one in pagination

CODA inspects git status/git diff, stages only the files relevant to the current change (never a blind git add -A), writes a Conventional Commits message if you didn't supply one, and commits. The commit itself goes through the same approval rules as any other shell command — in read-only mode it's blocked like anything else that writes.

/diff and the changes panel

/diff prints your current working-tree diff (staged, unstaged, and untracked files) — read-only, no arguments.

For a running view of everything a session has touched, open the changes panel:

• Click ▸ View changes in the sidebar, or run /changes (/changes 3 jumps straight to the third file, /changes close exits).
• The panel lists every file this session edited, with a per-file unified diff against HEAD.
• /changes before toggles whether files edited before this session are included.

Requires a Git repository and a terminal at least 90 columns wide.

See also

• Make Changes Safely — checkpoints, approvals, and the undo workflow these commands build on.
• Sessions & Checkpoints — exporting, importing, and resuming sessions.
• Agents — delegating work instead of doing it in the main session.

Voice

/voice turns your microphone into a push-to-talk input for CODA: speak your message instead of typing it. It runs fully offline, on macOS, Windows, and Linux. A cloud option via Glob.AI OS is coming soon.

Getting started

Set up Whisper — a free, offline speech-to-text engine CODA runs on your own machine. You only need a recorder installed first.

Installing a recorder

CODA needs a command-line audio recorder on your computer to capture your voice. It looks for ffmpeg first, then sox. If neither is found, CODA tells you so and points you at /voice setup.

Run /voice setup any time for the full, OS-specific instructions.

Set up Whisper

Whisper is a program that CODA runs on your own computer to turn your voice into text — nothing is sent anywhere. You only do this once.

Step 1 — Make sure you have git and a C++ compiler. If you can already run git and build other projects on your machine, you have what you need. (macOS: Xcode Command Line Tools. Windows: Visual Studio Build Tools. Linux: build-essential or equivalent.)

Step 2 — Download and build Whisper. Open a terminal in your project folder and run:

git clone https://github.com/ggml-org/whisper.cpp .coda/voice/whisper.cpp
cd .coda/voice/whisper.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j --config Release

This takes a few minutes. (On Windows, run the same commands from a terminal that has your C++ compiler set up, such as the "Developer Command Prompt for VS".)

Step 3 — Download a speech-recognition model. Still inside .coda/voice/whisper.cpp, run one of these:

sh ./models/download-ggml-model.sh medium   # macOS / Linux
models\download-ggml-model.cmd medium       # Windows

medium understands English, Spanish, and Portuguese and is accurate enough for everyday use. (If your computer is slow or you're short on disk space, small or base also work, just less accurately.)

Step 4 — Tell CODA to use Whisper. Run coda, open /settings, go to Voice, and press ←/→ on the Backend field until it shows whisper. CODA saves this for you in ~/.coda/config.json.

Step 5 — Try it. Type /voice, press Space, say something, and press Space again. If CODA doesn't find the recorder or the Whisper build, the same Voice settings screen shows exactly what's missing.

That's the whole setup. From here on, /voice just works — see Using voice mode below for the day-to-day controls.

Using voice mode

Once voice is set up, this is the everyday flow:

1. Type /voice to arm voice mode. CODA shows a banner confirming the backend, language, and model in use.
2. Press Space (with an empty input box) to start recording.
3. Press Space again to stop. CODA transcribes the clip and sends it as your next message, tagged [voice] so the model knows it came from speech.

A few more things worth knowing:

• Press Esc at any point to cancel the current clip without sending it; voice mode stays armed.
• /voice quit (aliases q, stop, off) exits voice mode. Typing /voice again while voice mode is on starts or stops a recording, the same as pressing Space; it does not turn voice mode off.
• A clip can last up to 60 seconds. If the agent is still busy with the previous turn when you stop recording, the clip is queued and transcribed as soon as the agent is free.

Changing settings

The easiest way is /settings → Voice. Open /settings while CODA is running, go to Voice, and use the ↑/↓ arrows to move between fields and ←/→ to change the selected one:

• Language — auto, es, en, or pt.
• Microphone — auto, or a specific device CODA detected.
• Keep recordings — on keeps every clip under ~/.coda/voice/recordings; off (default) deletes each clip after it's transcribed.
• Session mode — continuous (default) keeps voice mode on between clips; one-shot exits voice mode after one clip.

Each change saves immediately — no restart needed. The same screen also shows a live checklist (recorder found, Whisper build found, and so on), so you can see exactly what's missing.

If you'd rather edit a file directly, the same settings live under the voice block in config.json (or ~/.coda/config.json for every project):

{
  "voice": {
    "language": "auto", // "auto" | "es" | "en" | "pt"
    "device": ":1", // optional explicit device (overrides auto-selection)
    "keepRecordings": false, // keep the WAV file instead of deleting it
    "sessionMode": "continuous" // "continuous" (default) | "one-shot"
  }
}

A project's .coda/config.json wins over the global one — if you change a setting in /settings and nothing happens, check whether the current project already sets voice in its own config.

Whisper details

Runs fully offline via whisper.cpp, no network and no cost. CODA looks for the binary in this order: CODA_WHISPER_BIN → <project>/.coda/voice/whisper.cpp/build/bin/whisper-cli → ~/.coda/voice/whisper.cpp/build/bin/whisper-cli → your PATH. Set CODA_WHISPER_MODEL to point at a specific model file, and CODA_WHISPER_GPU=1/0 to force GPU on or off. By default whisper uses the GPU only on Apple Silicon Macs and runs on the CPU everywhere else, because the GPU path produces corrupted transcripts on Intel Macs.

Subcommands

Settings and environment variables

The other voice variables are in the Configuration Reference.

Voice in your editor

An editor connected over ACP can send a recorded audio clip as a prompt. CODA transcribes it and delivers it as a [voice] message, the same as a spoken turn in the terminal. Only audio/wav clips are accepted. See Use CODA in Your Editor (ACP).

Cost and attribution

Voice is free: Whisper runs on your own machine, so there's no per-clip cost.

Known limitations

• One clip at a time. While a clip is transcribing, pressing Space again is rejected until it's sent.
• sox ignores CODA_AUDIO_DEVICE. If you need explicit device selection, use ffmpeg.
• Windows device names must be exact. If CODA can't find a microphone on its own, set CODA_AUDIO_DEVICE to the name ffmpeg -list_devices true -f dshow -i dummy reports.
• Supported languages: auto, es, en, pt.

See also

• Commands & Flags — the full command list, including /voice.
• Tools Reference — other ways CODA reads non-text input, like omni_parser.

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.

Scheduling recurring runs with coda schedule

For headless runs that need to happen on their own, on a recurring cadence, coda schedule persists the job definition and drives it without you keeping a terminal open:

coda schedule add --cron "0 * * * *" "Summarize the last hour of commits and post to #releases"
coda schedule list
coda schedule pause <id|name>
coda schedule resume <id|name>
coda schedule remove <id|name>
coda schedule run <id|name>     # run it once, right now
coda schedule log <id|name>     # see its recent output

Cron expressions use the standard 5-field format (minute hour day month weekday), including @hourly/@daily/@weekly/@monthly/@yearly aliases. Each scheduled run launches coda -p "<prompt>" (or --goal for an autonomous run) in the schedule's working directory, and only inherits project trust if that directory is already in your trusted folders list.

Something has to actually tick the clock:

• coda schedule daemon [--interval seconds] runs a foreground loop (default: every 60 seconds) that checks for due schedules — leave it running in a terminal, tmux session, or background process.
• coda schedule install sets up the ticker for your OS. On macOS it writes a LaunchAgent (com.coda.schedule.plist) and prints the launchctl load -w command that loads it. On Linux it prints a crontab line for you to add with crontab -e; it doesn't edit your crontab. On Windows it prints how to run coda schedule daemon yourself, or from Task Scheduler. --print shows the macOS or Linux text without writing anything.
• coda schedule tick runs any due schedules once and exits — this is what your OS's own cron or launchd actually calls.

Schedules persist in ~/.coda/schedules.json; each run's output is logged under ~/.coda/schedules/<id>.log.

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

Voice prompts. An editor can send a recorded audio/wav clip as a prompt. CODA transcribes it and treats it as a [voice] message. See Voice.

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.

Trusted folders

Before permission modes even apply, CODA checks whether the current project is trusted. A project you haven't reviewed could ship a .coda/config.json or .coda/mcp.json that defines hooks, extensions, skills, plugins, or MCP servers that run code the moment CODA starts. Trust is the gate that keeps an unreviewed clone from doing that silently.

An untrusted project still works, but the hooks, extensions, skill folders, and plugins in its .coda/config.json, and the MCP servers in its .coda/mcp.json, are ignored for the run. Permissions, model, and rules still apply. When the project has a .coda/config.json or .coda/mcp.json, you'll see:

Folder not trusted: <dir>
Its .coda hooks, extensions, skills roots and MCP servers are ignored this run. Trust it with `coda trust` (or `--trust` for one run) once you have reviewed .coda/.

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. Detects your OS and shell dialect — macOS/Linux maps to bash, Windows PowerShell/pwsh maps to pwsh; if it's ambiguous, it asks.
2. Explores the project — reads AGENTS.md, package.json, CI workflows, and your command history to understand what commands the project actually runs.
3. Proposes a rule set in your shell's dialect — Bash(...) rules on macOS/Linux, PowerShell(...) rules on Windows (file and MCP rules are dialect-independent), and confirms risky ones with you before applying. Bash(*)/PowerShell(*) wildcards are explicitly refused as floor-relaxers.
4. Picks the scope — project (.coda/config.json, shareable with teammates) or global (~/.coda/config.json).
5. Applies via propose_policy — the same sanctioned, approval-gated path used by the /permissions command.
6. 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": 100000  // optional; prompts the user after N auto-approvals (default 100000 when the check is enabled)
    }
  }
}

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.
• Approves routine work, rejects only irreversible damage. The classifier approves normal development work — commits, rebases, non-force pushes, git worktree, tests, builds, linters and formatters (including --fix/--write), dependency installs, and file changes inside the project. It rejects only actions with a concrete, unrecoverable effect, such as git reset --hard, force-pushing shared history, deletes outside the project, dropping databases, or leaking secrets.
• 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.

The agents panel

/agents panel opens a side panel with a tree of every run in the session — main plus all child (and grandchild) agent runs — each with a live status glyph (running, completed, failed, cancelled, queued). The panel is the sidebar expanded, so the transcript stays visible next to it. Select a run to watch its transcript stream in real time, alongside any files it has produced so far. Use ↑/↓ to move between runs, ←/→ to collapse or expand a branch, a to toggle the side-by-side view, x to stop the selected run, Enter to open its full transcript as a session, and Esc or /agents panel close to close the panel. The sidebar also shows a compact version of the same tree, with a ▸ View agents row that opens the panel, for as long as the session has any agent runs, finished ones included. Requires a terminal at least 90 columns wide.

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.

Permission mode persists across resume

A session remembers the permission mode it was in when saved — resuming with --lastsession, --session-id, or /sessions continues in that mode instead of resetting to your configured default. The exception: if managed policy has since disabled that mode, CODA falls back to default and tells you why. Headless runs, sub-agents, and non-interactive SDK sessions don't persist mode changes.

Export and import sessions

Share a session with a teammate, or move one between machines:

/export [md|json] [path]

In /export, md (the default) produces a readable Markdown transcript. json produces a lossless export — ordered messages plus aggregated usage — that coda session import can read back as a brand-new session.

From the shell:

coda session list [--all] [--json] [--limit N]
coda session show <id|last>
coda session export <id|last> [--format json|md] [--out FILE]
coda session import <file> [--project DIR] [--continue]
coda session delete <id>

Unlike /export, coda session export writes JSON by default; pass --format md for a Markdown transcript. Only the JSON export can be imported again.

coda session import also understands other tools' transcripts, so you can continue a conversation you started elsewhere:

coda session import claude-code [--list | --pick N | --last | --all] [--continue]
coda session import codex [--list | --pick N | --last | --all] [--continue]

These scan ~/.claude/projects/ or ~/.codex/sessions/ for conversations that match your current project, let you pick one (or import all of them), and --continue opens the imported session immediately.

Isolate a session in its own Git worktree

coda --worktree [name]

Creates (or reuses) a Git worktree under .coda/worktrees/<name> — a random name is generated if you omit one — checks out a branch of the same name, and runs the session there. This is useful for running two sessions on the same repo in parallel without them stepping on each other's uncommitted changes. The worktree is kept on exit; resume it with cd <dir> && coda --lastsession, or remove it with git worktree remove <dir> when you're done.

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, and authorizationToken for remote ones; timeout for either kind; and disabled: true to keep a server defined but off. timeout is in seconds and limits every request to the server (connecting, listing, reading, and calling tools); leave it unset to use the default of 60 seconds. 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.

Manage servers from the shell

coda mcp add <name> --url <URL> [--oauth [--client-id <id>]] [--header K=V]...
coda mcp add <name> -- <command> [args...]      # local (stdio) server
coda mcp remove <name>
coda mcp list
coda mcp login <name>
coda mcp logout <name>

add defaults to project scope when .coda/ exists in the current directory, global otherwise (--scope global|project to override). --header is for HTTP servers; --env is for stdio servers. Use --client-id for a server that doesn't support dynamic client registration.

coda mcp login <name> runs the OAuth flow for a server that requires it — it opens your browser via a local loopback redirect and stores the token under ~/.coda/mcp-oauth/. coda mcp logout <name> clears it.

How CODA uses MCP tools

You don't call MCP tools by name. CODA exposes gateway tools — mcp_execute for calling a tool, and mcp_resource / mcp_prompt for servers that also publish resources or prompt templates — and the system prompt lists every connected server with what it exposes. 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.

A server that's configured but fails to connect is listed as unavailable (with its error) in the prompt instead of silently disappearing, so CODA doesn't claim an integration doesn't exist when it's just temporarily down.

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.

Skills from other agent ecosystems

CODA can also discover skills written for other agent CLIs, so you don't have to duplicate a skill your team already maintains elsewhere. Configure which sources are active under skills.sources in config.json:

{
  "skills": {
    "sources": {
      "agents": true, // .agents/skills/ — on by default
      "claude": false, // .claude/skills/ — opt-in
      "codex": false, // .codex/skills/ — opt-in
      "opencode": false // .opencode/skills/ — opt-in
    },
    "paths": ["/extra/skills/root"] // additional root directories to scan
  }
}

Native .coda/skills/ is always scanned. When the same skill name exists in more than one place, the first match wins. CODA checks every project folder before any global folder, so a project skill beats a global skill even when the global one comes from a higher-priority source (a project .claude/skills skill beats a global ~/.coda/skills skill). Within the project folders, and again within the global folders, the order is coda > agents > claude > codex > opencode, then any skills.paths.

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

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

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"
          }
        ]
      }
    ]
  }
}

CODA ships this pattern as a one-liner: coda hooks install-format adds a PostToolUse hook that runs coda hooks format-file after every write or edit. It picks a formatter for the file: Biome or Prettier for JS/TS files, when the project has a Biome or Prettier config file; ruff check --fix (or black) for Python; gofmt for Go; rustfmt for Rust. Formatter errors go back to the model so it can fix them. Files with no matching formatter are left alone.

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

Planning, review & collaboration

Voice

Background processes

Autonomous mode

/goal and /loop are on by default. Each one shows a warning that tokens can add up fast every time you run it. Choose "Continue" to run, or "Continue and don't show this again" to run and silence the warning for that command. Turn both commands off together from /settings → Autonomy.

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.

voice

Used by /voice. See Voice for the full guide.

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

git

Controls the optional commit after each turn. See Make Changes Safely.

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.

sessionActivity

Reports session and turn-level activity to your organization's glob.ai-os gateway for observability. It only works on Glob.AI OS 2 (Platform Gateway) profiles, and it is read only from your global config (~/.coda/config.json): a project .coda/config.json that sets it is ignored, with a warning. It is also gated by the same telemetry.level settings as OTLP export. /settings → Session Activity edits all three fields below and shows whether telemetry is currently blocking reporting.

notifications

Signal you when a turn finishes or needs input. Off by default.

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.

Tool Lazy Loading

To keep the system prompt small, CODA only sends the full schema of a handful of core tools (bash, read, write, edit, grep, glob, background_output, ask_user, skills, mcp_execute, mcp_describe, load_tool) on every turn. Every other tool — memory, examine_images, omni_parser, repo_map, agent/workflow tools, and anything from MCP, extensions, or plugins — is listed by name and one-line description only, under a "Deferred tools" note. When the model needs one, it calls the built-in load_tool tool with the names it wants, and the full schema becomes available for the rest of the session.

You don't need to do anything for this to work — it's transparent and automatic. To see every schema on every turn instead (more tokens per turn, nothing to load on demand), set "lazyTools": false at the top level of config.json.

Background shell processes

Pass background: true to the bash tool to start a long-running command and get control back immediately, instead of waiting for it to finish:

bash { command: "npm run dev", background: true }
→ Started background process bg-a1b2c3 (pid 1234): npm run dev

• background_output { id, wait_ms, stop } reads new output since the last read (optionally waiting up to wait_ms for more), or terminates the process when stop: true.
• /ps lists the current session's background processes with their status and uptime; /stop <id|all> stops one or all of them.

Background processes are scoped to the session — they're cleaned up when the session ends.

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

Remap shortcuts

You can remap 15 actions in ~/.coda/keybindings.json:

{
  "toggleSidebar": "ctrl+e",
  "scrollUp": "alt+up",
  "clearQueue": "ctrl+k"
}

The actions are exit, clear, toggleCollapsible, scrollUp, scrollDown, scrollPageUp, scrollPageDown, scrollToTop, scrollToBottom, copyLastCodeBlock, toggleSidebar, cycleFavoriteModel, cyclePermissionMode, clearQueue, and imagePaste. Other shortcuts are fixed.

A chord combines ctrl, alt, shift, or meta with a letter or a named key: up, down, left, right, pageup, pagedown, home, end, tab, escape, or enter. The six scroll actions (scrollUp, scrollDown, scrollPageUp, scrollPageDown, scrollToTop, scrollToBottom) only work with a named key, so "scrollUp": "alt+up" works and "scrollUp": "ctrl+k" never fires. Unknown actions or malformed chords are reported when CODA starts and ignored.

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.

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.5.0 — October 16, 2026

This is CODA's biggest release yet: a new voice interface, read-only planning with /plan, automated PR review with coda review and coda github install (experimental), persistent scheduled runs with coda schedule, a codebase map tool (repo_map), background shell processes, trusted folders, /goal and /loop on by default, a major round of performance work (typing, startup, and large-workspace fixes), and a set of reliability fixes. Non-core tools now load lazily to keep prompts smaller.

Voice

• /voice — push-to-talk speech-to-text. Press /voice, tap space to record, tap space again to stop — your speech arrives as a normal message, tagged [voice] for the model. Works on macOS, Windows, and Linux with ffmpeg or sox on your PATH. → Voice
• Two backends. api (default) sends audio to Glob.AI OS (openai/gpt-4o-transcribe) and authenticates with either your OAuth session or a static CODA_VOICE_API_KEY. whisper runs fully offline via whisper.cpp — no network, no cost. Configure under the voice block in config.json or with CODA_VOICE_BACKEND. The api backend needs a Glob.AI OS 2 sign-in unless you set CODA_VOICE_API_KEY. → Voice
• Per-clip cost in /usage. The api backend's cost appears under its own Voice row in the sidebar and the /usage overlay; whisper is free. → Voice
• /voice setup prints OS-specific install instructions; /voice lang <auto|es|en|pt> sets the session's transcription language; /voice context <text> attaches a one-shot note to the next spoken turn. → Voice

Planning, Review & Collaboration

• /plan — read-only planning. /plan <goal> switches the session to read-only, investigates, and writes an editable plan to .coda/plans/. Review or edit the file, then /plan approve (optionally --auto) restores your permission mode and runs the plan as a /goal until every acceptance item is checked off. → Plan, Review & Collaborate
• /commit — governed Conventional Commits. Stages only the files relevant to the current change (never a blind git add -A), writes a Conventional Commits message, and commits — gated by the same approval rules as any other shell command. → Plan, Review & Collaborate
• /council (alias /compare) — ask several models at once. /council <question> (or /compare) sends the same question to 2–5 models in parallel, streaming each in its own column, then synthesizes a recommendation. Pick members explicitly with --models a,b,c, or let it use your starred favorites. /council use <n|synthesis> continues the conversation with the chosen answer. → Plan, Review & Collaborate
• /btw (alias /side) — side questions that never touch the conversation. Ask a quick question without disturbing the main session's context. A small read-only helper agent answers it in a side panel — it can search the web, read files, and run read-only commands — and the answer is never added to the transcript. → Plan, Review & Collaborate
• coda review (experimental) — PR and branch review. Review a PR (--pr <n>), a branch, a single commit, or uncommitted changes. Findings are scored 🔴 critical / 🟠 high / 🟡 medium / 🟢 low and written to .coda/reviews/. With --pr it also posts the findings on the pull request, and --fail-on (default medium) makes the command fail CI. → Plan, Review & Collaborate
• coda github install (experimental) — review PRs in GitHub Actions. Wires coda review into a GitHub Actions workflow that reviews every PR and responds to /coda mentions. → Plan, Review & Collaborate
• /diff and the changes panel. /diff shows your working-tree diff read-only; the sidebar's ▸ View changes (or /changes [n|close]) opens a full per-file diff panel for everything touched this session. → Plan, Review & Collaborate
• Session export/import. /export [md|json] saves the current session; coda session export/import/list/show/delete manage sessions from the shell, including coda session import claude-code|codex to continue a Claude Code or Codex conversation in CODA. → Sessions & Checkpoints
• --worktree [name] runs a session in an isolated Git worktree under .coda/worktrees/, so parallel sessions never collide on the same branch. The worktree is kept on exit for you to resume or remove manually. → Sessions & Checkpoints

Tools & Automation

• repo_map tool. An on-demand, PageRank-ranked map of a repo's top-level definitions (classes, functions, exports), built with ripgrep. The model calls it when it needs an overview instead of the map being injected into every prompt. → Tools Reference
• Background shell processes. bash accepts background: true to start a long-running command and return immediately; background_output reads or stops it later, and /ps / /stop <id|all> manage running processes from the TUI. → Tools Reference
• mcp_resource and mcp_prompt tools. List and read resources, and list and render prompt templates, published by MCP servers that expose more than tools. Both respect the managed allowManagedMcpServersOnly lockdown. → MCP Servers
• Tool Lazy Loading. Non-core tools are listed by name and description in the system prompt; the model calls the built-in load_tool to fetch a tool's full schema only when it needs it, shrinking the per-turn prompt. Core tools (bash, read, write, edit, grep, glob, and a few others) are always loaded. Disable with lazyTools: false. → Tools Reference
• Agents panel. /agents panel (or /agents panel all for a side-by-side view) opens a tree of the current session's agent runs with live child transcripts — complements the existing /agents manager. → Agents
• Post-edit format/lint hook. coda hooks install-format wires a PostToolUse hook that runs the project's formatter (Biome/Prettier, ruff, gofmt, rustfmt — auto-detected) after every write/edit, surfacing errors back to the model. → Hooks
• Auto-commit after each turn. Set git.autoCommit to commit exactly the files each turn changed, with a coda: <your prompt> message, so every step is reviewable and revertible from Git history. Off by default, and it never commits secrets or CODA's own database files. → Make Changes Safely

Autonomy

• /goal and /loop are on by default. Both commands now work out of the box. Each shows a token-spend warning every time you run it, and you can silence it per command from the warning itself. One switch, autonomy.enabled, turns both off, from the Autonomy panel in /settings. → Commands & Flags
• coda schedule — persistent cron-driven runs. coda schedule add --cron "<expr>" "<prompt>" (plus list/remove/pause/resume/run/log) schedules headless runs that execute on their own, driven by coda schedule daemon or your OS's own cron/launchd via coda schedule install. → Automate with Batch Mode
• Session permission mode persists across resume. Resuming a session (--lastsession, --session-id, /sessions) now continues in the mode it was saved with, instead of resetting to your configured default — unless managed policy has since disabled that mode. → Sessions & Checkpoints

Trust & Permissions

• Trusted folders. coda trust [dir] (or /trust inside a session) marks a project as trusted; an untrusted project's .coda hooks, extensions, skills, and MCP servers are ignored until you review and trust it. coda --trust trusts for a single run without persisting. → Permissions & Approvals
• init-rules proposes rules for your actual shell. The skill now detects whether you're on bash/zsh or PowerShell and proposes Bash(...) or PowerShell(...) rules accordingly, instead of a single bash-flavored set. → Bootstrapping rules with init-rules
• The LLM safety check approves routine development work. In auto mode with permissions.llmSafetyCheck enabled, the classifier no longer rejects by default: commits, test runs, builds, linters and formatters that rewrite files, dependency installs, and git worktree are now approved, and rejection is reserved for irreversible damage (discarding uncommitted work, force-pushing shared history, deletes outside the project, secret exfiltration). Deny rules and the catastrophic floor still apply. → Permissions & Approvals
• Fresh installs start in auto mode. A CLI config with no permissions block now starts the session in auto, and after your first message CODA offers to run /init-rules so you can set your own rules. The silent auto applies to that session only and is never saved; a config that already has a permissions block keeps its mode. Turn the offer off with onboarding.suggestInitRules: false. → Permissions & Approvals
• The safety check's nudge is quieter. When permissions.llmSafetyCheck is enabled, nudgeThreshold now defaults to 100000 instead of 10. → Permissions & Approvals
• Project env files no longer reach tools, hooks, or MCP servers. (Breaking change for projects that keep variables in .coda/.env or .env.) CODA no longer copies the project's env file into the process environment, because in a cloned repository that file comes from the repository. Bash commands, git, hooks, MCP servers, and a profile's secretRef no longer see those variables: export them in your shell or keep them in ~/.coda/.secrets. ${VAR} references in config, including an MCP server's env, headers, and authorizationToken, still read the project env file. → Configuration Reference
• The native binary no longer auto-loads .env and bunfig.toml. CODA used to load both from the directory it started in, before its own trust check. It now reads only .coda/.env (or .env when that is absent) itself, so variables kept only in .env.local, .env.development, or a second env file need to move there or be exported in your shell.

MCP

• coda mcp add/remove/list/login/logout manage servers and OAuth logins directly from the shell, including --client-id for servers that don't support dynamic client registration. → MCP Servers

Telemetry

Telemetry is exported only from Glob.AI OS 2 (Platform Gateway) profiles; other profiles export nothing.

• Session Activity reporting. CODA can report session and turn-level activity to your organization's glob.ai-os gateway for observability. Configure scope under sessionActivity in config.json (enabled, transcript, mode); it's gated by the same telemetry.level settings as OTLP export. → Configuration Reference
• Telemetry metrics changed. coda.session.started, coda.tool.invocations, and coda.tool.duration_ms are gone, and nothing replaces the tool metrics. New: coding_agent.active_time.total, coding_agent.lines_of_code.count, coding_agent.commit.count, coding_agent.pull_request.count, and coding_agent.prompt.length. coding_agent.session.count, coding_agent.token.usage, and coding_agent.cost.usage already existed. Update dashboards that reference the removed names.
• Telemetry shows which app started CODA. Every exported span, log, and metric now carries globant.client_via — coda-cli, coda-headless, or coda-acp by default, or the name a launcher sets in CODA_CLIENT_VIA. A launcher can also add its own labels through OTEL_RESOURCE_ATTRIBUTES (for example, stepwise.run_id=r-42); keys need a namespace of their own, reserved namespaces such as service or globant are dropped, and at most 32 labels are kept. → Configuration Reference
• Telemetry project comes from your sign-in. Telemetry is now attributed to the project of your signed-in session (then your profile) from startup, so it no longer lands at organization level. telemetry.projectId in config.json is ignored: a project config that sets it gets a warning, and a global config drops it silently. → Configuration Reference

Customization

• Output styles. Nine built-in styles (concise, explanatory, learning, spartan, visual, and more), plus default, which applies none, change how CODA formats its responses without changing what it does. Set outputStyle in config.json, pick one from /settings → Output Style, or list them with coda list-output-styles. → Configuration
• Four new UI themes. solarized, nord, high-contrast, and light join classic and modern. Pick one under /settings → UI Theme or set theme in config.json. → Configuration
• User keymap. Remap 15 built-in actions (scrolling, sidebar toggle, favorite-model cycling, and more) in ~/.coda/keybindings.json. → Keyboard Shortcuts
• Attention notifications. CODA can signal you when a turn finishes or needs input, via terminal bell, an OSC 9 desktop notification, or a custom shell command — configure under notifications in config.json. → Configuration
• Expand/collapse long tool output. Ctrl+O — the same shortcut used for Thinking blocks — now also expands or collapses long bash/grep/glob/MCP tool output in the transcript. → Keyboard Shortcuts
• Search in the profile picker. Press / inside /switch-profile to filter profiles by label, id, or provider. → Commands & Flags

Extensibility

• Skills from other agent ecosystems. Besides .coda/skills/ and .agents/skills/, which CODA already read, it can now discover skills from .claude/skills/, .codex/skills/, and .opencode/skills/ (all opt-in), with a switch for each under skills.sources and extra folders under skills.paths. → Skills
• @globant/coda-sdk 0.1.0-alpha.1. A new hexagonal SDK over @globant/coda-core for embedding CODA in-process (VS Code, Electron, Node hosts), with WorkflowCapability, ExtensionsCapability, a createTool() factory, and injectable runtime adapters. (Alpha, private registry — no impact for CLI users.)

Performance

• Typing is faster and lighter. Key-to-frame latency dropped from 8.4 ms to 2.0 ms (p50) and CPU usage while typing fell from 48% to 18%, with held-key repeat now rendering at 119 fps instead of 59 and memory use after typing about 35% lower.
• Typing stays fast in long sessions. The cost of each keystroke no longer grows with the size of the transcript: off-screen messages are skipped when the screen redraws, and editing the input box no longer re-lays out the whole screen.
• Startup is faster, especially with many saved sessions. Keychain restore now does a single direct lookup instead of enumerating every saved credential (cutting up to ~5 s of blocking time on a cold keyring), and OAuth refresh for still-valid tokens now runs in the background instead of blocking the first frame.
• The first message of a session responds 2–4 seconds sooner. CODA now pre-warms the checkpoint shadow repo and pre-stages the initial Git index while you're still on the home screen, so the first turn no longer waits on them.
• Fixed a severe stall in workspaces with many nested repositories. A checkpoint probe that walked the whole worktree, without skipping nested repositories or dependency folders, could add 40–180 seconds to every turn in a directory holding dozens of nested repos. It is now capped at 250 ms, honors nested repos and your .codaignore, and skips dependency and cache folders such as node_modules, .venv, .next, and .cache at any depth. dist, build, and target are still skipped only at the project root.
• CLI subcommands exit instantly instead of stalling ~3 seconds. coda --version, --help, logs, skills, and permissions no longer wait out a stale 2.5-second shutdown timer before exiting.
• Smoother streaming. Model output and tool results now render at most once per animation frame instead of once per token or output line.
• Long sessions stay fast. The context builder now reads only the messages since the last compaction directly from the database, instead of reading the full session history and discarding the old part on every turn.
• Smaller system prompt. Large MCP tool catalogs are now listed compactly, with full tool descriptions fetched on demand.

Bug Fixes & Reliability

• Token counts no longer double-count. Fixed a bug where some prompt content was counted twice in the session's token totals, which inflated the context bar and the usage and cost views.
• Clipboard image paste works in every terminal. Ctrl+V/Alt+V paste is no longer limited to a subset of terminal emulators.
• Session database self-heals. CODA validates and repairs the session database schema on open instead of failing.
• MCP reliability. The configured MCP timeout now applies to every request (not just the initial connection), and a server that fails to connect is now listed as "unavailable" in the prompt instead of silently vanishing.
• Windows sign-in sessions no longer fail to save. When a saved sign-in session is too large for the Windows Credential Manager, CODA now falls back to encrypted file storage automatically instead of failing to save it.

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