codi-cli

codi-cli / types

types

Interfaces

AgentAdapter

Defined in: types/agent.ts:122

The contract every adapter must implement to participate in Codi’s generation pipeline.

An adapter is responsible for translating Codi’s normalized configuration into the agent-specific file format and directory layout that a particular AI tool expects.

Properties

capabilities

capabilities: AgentCapabilities;

Defined in: types/agent.ts:137

Feature flags describing what this adapter can generate.

id

id: string;

Defined in: types/agent.ts:124

Unique, stable identifier for the adapter (e.g. “claude”, “cursor”, “windsurf”).

name

name: string;

Defined in: types/agent.ts:126

Human-readable display name for the adapter.

paths

paths: AgentPaths;

Defined in: types/agent.ts:135

File system paths this adapter writes generated files to.

Methods

detect()

detect(projectRoot): Promise<boolean>;

Defined in: types/agent.ts:133

Detects whether the adapter’s target agent is present in the given project.

Parameters

Returns

Promise<boolean>

A promise that resolves to true when the agent is detected.

generate()

generate(config, options): Promise<GeneratedFile[]>;

Defined in: types/agent.ts:145

Generates the full set of files for this adapter from the normalized configuration.

Parameters

Returns

Promise<GeneratedFile[]>

A promise resolving to the list of files that should be written to disk.

AgentCapabilities

Defined in: types/agent.ts:26

Feature flags indicating which generation features an adapter supports.

Properties

agents

agents: boolean;

Defined in: types/agent.ts:38

Whether the adapter can generate agent definition files.

frontmatter

frontmatter: boolean;

Defined in: types/agent.ts:34

Whether generated files include YAML frontmatter headers.

maxContextTokens

maxContextTokens: number;

Defined in: types/agent.ts:40

Maximum number of context tokens the agent supports; used for size budgeting.

mcp

mcp: boolean;

Defined in: types/agent.ts:32

Whether the adapter supports MCP server configuration.

progressiveLoading

progressiveLoading: boolean;

Defined in: types/agent.ts:36

Whether the adapter supports progressive/lazy loading of rules.

rules

rules: boolean;

Defined in: types/agent.ts:28

Whether the adapter can generate rule files.

skills

skills: boolean;

Defined in: types/agent.ts:30

Whether the adapter can generate skill files.

AgentFileStatus

Defined in: types/agent.ts:95

Status report for a single generated file after a generate() call.

Properties

hash?

optional hash?: string;

Defined in: types/agent.ts:101

SHA-256 hash of the file content after the operation, if available.

path

path: string;

Defined in: types/agent.ts:97

Path of the file, relative to the project root.

status

status: FileStatus;

Defined in: types/agent.ts:99

The outcome of the write operation for this file.

AgentPaths

Defined in: types/agent.ts:8

File system paths that an adapter writes generated files to.

Each path is relative to the project root.

Properties

agents

agents: string | null;

Defined in: types/agent.ts:16

Directory where agent definition files are written, or null if not supported.

configRoot

configRoot: string;

Defined in: types/agent.ts:10

Root directory where the agent stores its configuration files.

instructionFile

instructionFile: string;

Defined in: types/agent.ts:18

Path to the primary instruction file consumed by the agent (e.g. CLAUDE.md).

mcpConfig

mcpConfig: string | null;

Defined in: types/agent.ts:20

Path to the MCP server configuration file, or null if MCP is not supported.

rules

rules: string;

Defined in: types/agent.ts:12

Directory where rule files are written.

skills

skills: string | null;

Defined in: types/agent.ts:14

Directory where skill files are written, or null if the agent does not support skills.

AgentStatus

Defined in: types/agent.ts:107

Summary of a completed adapter generate() call, including file counts and errors.

Properties

agentId

agentId: string;

Defined in: types/agent.ts:109

Identifier of the adapter that produced this status.

agentName

agentName: string;

Defined in: types/agent.ts:111

Human-readable display name of the adapter.

files

files: AgentFileStatus[];

Defined in: types/agent.ts:113

Per-file status entries for every file touched during the generate() call.

FlagConditions

Defined in: types/flags.ts:41

Conditions that gate a “conditional” flag.

At least one field must be set. Multiple fields are evaluated with AND logic.

Properties

agent?

optional agent?: string[];

Defined in: types/flags.ts:43

Agent ids this condition applies to (e.g. [“claude-code”, “cursor”]).

file_pattern?

optional file_pattern?: string[];

Defined in: types/flags.ts:45

File glob patterns this condition applies to (e.g. [”**/*.test.ts”]).

FlagDefinition

Defined in: types/flags.ts:25

A single flag entry as stored in .codi/flags.yaml.

Flags control feature toggles and configuration values that are passed to agent instruction files during generation.

Properties

conditions?

optional conditions?: FlagConditions;

Defined in: types/flags.ts:33

Conditions that determine when a “conditional” mode flag applies.

locked?

optional locked?: boolean;

Defined in: types/flags.ts:31

When true, this flag cannot be modified by codi flags set — only direct file edits.

mode

mode: FlagMode;

Defined in: types/flags.ts:27

How Codi manages this flag’s value.

value?

optional value?: unknown;

Defined in: types/flags.ts:29

The flag’s value. Only used when mode is “enforced” or “enabled”.

FlagSpec

Defined in: types/flags.ts:71

A flag specification used by the CLI to validate and describe flags.

Properties

default

default: unknown;

Defined in: types/flags.ts:75

The default value for this flag when not explicitly set.

description

description: string;

Defined in: types/flags.ts:83

Human-readable description shown in CLI help output.

hint?

optional hint?: string;

Defined in: types/flags.ts:85

Short hint displayed alongside the flag in interactive prompts.

hook?

optional hook?: string | null;

Defined in: types/flags.ts:81

Optional hook identifier invoked when this flag changes.

min?

optional min?: number;

Defined in: types/flags.ts:79

Minimum numeric value for number-typed flags.

type

type: "number" | "boolean" | "enum" | "string[]";

Defined in: types/flags.ts:73

The data type of this flag’s value.

valueHints?

optional valueHints?: Record<string, string>;

Defined in: types/flags.ts:87

Descriptive labels for each allowed enum value, shown in interactive prompts.

values?

optional values?: string[];

Defined in: types/flags.ts:77

Allowed values for enum-typed flags.

GeneratedFile

Defined in: types/agent.ts:46

A single file produced by an adapter’s generate() call.

Properties

binarySrc?

optional binarySrc?: string;

Defined in: types/agent.ts:56

Absolute source path for binary files that must be copied as-is (not text-written).

content

content: string;

Defined in: types/agent.ts:50

Text content to write to the file.

hash

hash: string;

Defined in: types/agent.ts:54

SHA-256 hash of the file content, used for change detection.

path

path: string;

Defined in: types/agent.ts:48

Destination path of the file, relative to the project root.

sources

sources: string[];

Defined in: types/agent.ts:52

List of source artifact identifiers (rules, skills, etc.) that contributed to this file.

GenerateOptions

Defined in: types/agent.ts:62

Options passed to an adapter’s generate() method.

Properties

agents?

optional agents?: string[];

Defined in: types/agent.ts:64

Subset of agent IDs to generate for; when omitted all detected agents are targeted.

dryRun?

optional dryRun?: boolean;

Defined in: types/agent.ts:66

When true, compute and return files without writing them to disk.

force?

optional force?: boolean;

Defined in: types/agent.ts:68

When true, overwrite existing files even if their content is unchanged (maps to —on-conflict keep-incoming).

keepCurrent?

optional keepCurrent?: boolean;

Defined in: types/agent.ts:70

Non-interactive mode: skip all conflicting files without prompting (maps to —on-conflict keep-current).

projectRoot?

optional projectRoot?: string;

Defined in: types/agent.ts:78

Absolute path to the project root; defaults to the current working directory.

unionMerge?

optional unionMerge?: boolean;

Defined in: types/agent.ts:76

Auto-merge every conflict with git-style markers (union strategy). Non-overlapping hunks apply cleanly; overlapping hunks keep both sides wrapped in <<<<<<< / ======= / >>>>>>> so the user resolves in-editor.

McpConfig

Defined in: types/config.ts:212

The parsed MCP server configuration from .codi/mcp.yaml.

Properties

servers

servers: Record<string, {
  args?: string[];
  command?: string;
  enabled?: boolean;
  env?: Record<string, string>;
  headers?: Record<string, string>;
  type?: "stdio" | "http";
  url?: string;
}>;

Defined in: types/config.ts:217

Map of server name to server configuration. Keys are the MCP server identifiers referenced in agent frontmatter mcpServers.

NormalizedAgent

Defined in: types/config.ts:161

A fully normalized agent definition, ready for generation.

Produced by the config parser after reading a .codi/agents/<name>.md file.

Properties

background?

optional background?: boolean;

Defined in: types/config.ts:202

When true, this agent runs as a background process.

color?

optional color?: string;

Defined in: types/config.ts:206

Color label shown in the Claude Code UI for this agent.

content

content: string;

Defined in: types/config.ts:169

The full Markdown body (system prompt) of the agent.

description

description: string;

Defined in: types/config.ts:165

Human-readable description of what this agent does.

disallowedTools?

optional disallowedTools?: string[];

Defined in: types/config.ts:173

Tool names explicitly disallowed for this agent.

effort?

optional effort?: "high" | "medium" | "low" | "max";

Defined in: types/config.ts:179

Model effort tier.

isolation?

optional isolation?: string;

Defined in: types/config.ts:204

Run this agent in an isolated git worktree copy when set to "worktree".

managedBy?

optional managedBy?: "codi" | "user";

Defined in: types/config.ts:181

Ownership.

maxTurns?

optional maxTurns?: number;

Defined in: types/config.ts:177

Maximum number of agentic turns before the agent stops.

mcpServers?

optional mcpServers?: string[];

Defined in: types/config.ts:191

MCP server names to attach from the project’s mcp.yaml.

memory?

optional memory?: "user" | "project" | "none";

Defined in: types/config.ts:200

Memory scope for this agent.

• "user" — user-level memory persists across projects
• "project" — project-level memory persists within this project
• "none" — no persistent memory

model?

optional model?: string;

Defined in: types/config.ts:175

Model identifier override. Omit to use the platform default.

name

name: string;

Defined in: types/config.ts:163

Unique kebab-case agent identifier.

permissionMode?

optional permissionMode?: "unrestricted" | "readonly" | "limited";

Defined in: types/config.ts:189

Claude Code tool access scope.

• "unrestricted" — all tools allowed
• "readonly" — only read operations
• "limited" — a curated subset of tools

skills?

optional skills?: string[];

Defined in: types/config.ts:193

Skill names this agent has access to.

tools?

optional tools?: string[];

Defined in: types/config.ts:171

Allowed tool names for this agent.

version

version: number;

Defined in: types/config.ts:167

Monotonically increasing schema version number.

NormalizedConfig

Defined in: types/config.ts:243

The fully resolved project configuration, produced by resolveConfig().

This is the single object passed to every adapter’s generate() method.

Properties

agents

agents: NormalizedAgent[];

Defined in: types/config.ts:251

All active agent definitions.

flags

flags: ResolvedFlags;

Defined in: types/config.ts:253

Resolved flag values with source tracking.

manifest

manifest: ProjectManifest;

Defined in: types/config.ts:245

Parsed project manifest.

mcp

mcp: McpConfig;

Defined in: types/config.ts:255

Parsed MCP server configuration.

rules

rules: NormalizedRule[];

Defined in: types/config.ts:247

All active rules in priority order.

skills

skills: NormalizedSkill[];

Defined in: types/config.ts:249

All active skills.

NormalizedRule

Defined in: types/config.ts:76

A fully normalized rule, ready for generation by any adapter.

Produced by the config parser after reading a .codi/rules/<name>.md file and validating its frontmatter.

Properties

alwaysApply

alwaysApply: boolean;

Defined in: types/config.ts:98

When true, the rule is injected unconditionally into every agent context.

content

content: string;

Defined in: types/config.ts:84

The full Markdown body of the rule (content after frontmatter).

description

description: string;

Defined in: types/config.ts:80

Human-readable description of what this rule enforces.

language?

optional language?: string;

Defined in: types/config.ts:89

Optional language hint (e.g. "typescript", "python"). Adapters may use this to produce path-scoped rules.

managedBy

managedBy: "codi" | "user";

Defined in: types/config.ts:100

Ownership: "codi" means preset-managed; "user" means user-managed.

name

name: string;

Defined in: types/config.ts:78

Unique kebab-case rule identifier (e.g. "codi-typescript").

priority

priority: "high" | "medium" | "low";

Defined in: types/config.ts:91

Injection priority: "high" rules appear first, "low" rules appear last.

scope?

optional scope?: string[];

Defined in: types/config.ts:96

File glob patterns that restrict this rule to matching files only. When set, the rule is not injected for files that don’t match.

version

version: number;

Defined in: types/config.ts:82

Monotonically increasing schema version number.

NormalizedSkill

Defined in: types/config.ts:108

A fully normalized skill, ready for generation by any adapter.

Produced by the config parser after reading a .codi/skills/<name>/SKILL.md file.

Properties

agent?

optional agent?: string;

Defined in: types/config.ts:145

Name of a registered Codi agent to run this skill as.

allowedTools?

optional allowedTools?: string[];

Defined in: types/config.ts:126

Tool names that are explicitly allowed for this skill.

argumentHint?

optional argumentHint?: string;

Defined in: types/config.ts:124

Hint shown to users when invoking: /skill-name <hint>.

category?

optional category?: string;

Defined in: types/config.ts:128

Skill category for routing and discovery (e.g. "engineering", "content").

compatibility?

optional compatibility?: string[];

Defined in: types/config.ts:118

Agent platform ids this skill targets (e.g. ["claude-code"]). Omit for all platforms.

content

content: string;

Defined in: types/config.ts:116

The full Markdown body of the skill.

context?

optional context?: "fork";

Defined in: types/config.ts:143

When set to "fork", the skill runs in an isolated Claude Code subagent context. The subagent inherits the project context but runs in its own session.

description

description: string;

Defined in: types/config.ts:112

Human-readable description shown in skill routing tables.

disableModelInvocation?

optional disableModelInvocation?: boolean;

Defined in: types/config.ts:122

When true, the skill runs as a pure tool execution with no LLM call.

effort?

optional effort?: "high" | "medium" | "low" | "max";

Defined in: types/config.ts:138

Model effort tier. "low" uses faster/cheaper models; "max" uses highest capability.

hooks?

optional hooks?: unknown;

Defined in: types/config.ts:153

Hook configuration for this skill.

license?

optional license?: string;

Defined in: types/config.ts:130

SPDX license identifier for this skill (e.g. "MIT").

managedBy?

optional managedBy?: "codi" | "user";

Defined in: types/config.ts:134

Ownership: "codi" means preset-managed; "user" means user-managed.

metadata?

optional metadata?: Record<string, string>;

Defined in: types/config.ts:132

Arbitrary key-value metadata attached to this skill.

model?

optional model?: string;

Defined in: types/config.ts:136

Model identifier override (e.g. "claude-opus-4-5"). Omit to use the agent default.

name

name: string;

Defined in: types/config.ts:110

Unique kebab-case skill identifier.

paths?

optional paths?: string[];

Defined in: types/config.ts:149

File glob patterns the skill is allowed to read or write.

shell?

optional shell?: "bash" | "powershell";

Defined in: types/config.ts:151

Shell interpreter for script-type skills.

tools?

optional tools?: string[];

Defined in: types/config.ts:120

Allowed tool names the skill may use.

userInvocable?

optional userInvocable?: boolean;

Defined in: types/config.ts:147

When true, users can invoke this skill via the /skill-name slash command.

version

version: number;

Defined in: types/config.ts:114

Monotonically increasing schema version number.

ProjectManifest

Defined in: types/config.ts:19

The parsed contents of a project’s codi.yaml manifest file.

This is the primary project configuration document. It lives at .codi/codi.yaml and controls which agents are targeted, which layers are active, and which presets are installed.

Properties

agents?

optional agents?: string[];

Defined in: types/config.ts:32

Subset of agent ids to generate configuration for. Omit to generate for all agents detected in the project.

Example

`["claude-code", "cursor"]`

description?

optional description?: string;

Defined in: types/config.ts:25

Optional human-readable description of this project.

engine?

optional engine?: object;

Defined in: types/config.ts:48

Minimum Codi engine version required to use this configuration.

layers?

optional layers?: object;

Defined in: types/config.ts:37

Controls which artifact layers Codi generates. All layers default to enabled when omitted.

name

name: string;

Defined in: types/config.ts:21

The project name used as the base for generated artifact names.

presetRegistry?

optional presetRegistry?: object;

Defined in: types/config.ts:57

Custom preset registry for codi preset install. When set, Codi fetches preset metadata from this GitHub repository instead of the default upstream registry.

presets?

optional presets?: string[];

Defined in: types/config.ts:67

Names of presets currently installed in this project. Populated automatically by codi preset install.

version

version: "1";

Defined in: types/config.ts:23

Schema version — always "1". Reserved for future migrations.

ResolvedFlag

Defined in: types/flags.ts:59

A single flag after resolution — value merged from project flags and agent defaults.

Properties

locked

locked: boolean;

Defined in: types/flags.ts:67

Whether this flag is locked from modification via the CLI.

mode

mode: FlagMode;

Defined in: types/flags.ts:63

The mode in effect for this flag after resolution.

source

source: string;

Defined in: types/flags.ts:65

Identifier of the source that provided this flag’s value (e.g. project, agent default).

value

value: unknown;

Defined in: types/flags.ts:61

The resolved value of the flag after merging project and agent defaults.

ResolvedFlags

Defined in: types/flags.ts:52

Map of flag name to its resolved value, keyed by the flag identifier.

Indexable

[key: string]: ResolvedFlag

Type Aliases

FileStatus

type FileStatus = "created" | "updated" | "unchanged" | "deleted" | "error";

Defined in: types/agent.ts:90

The outcome of writing a single generated file.

• “created” - file was newly created
• “updated” - file existed and was overwritten
• “unchanged” - file content was identical; no write needed
• “deleted” - file was removed during generation
• “error” - an error occurred while writing the file

FlagMode

type FlagMode = 
  | "enforced"
  | "enabled"
  | "disabled"
  | "inherited"
  | "delegated_to_agent_default"
  | "conditional";

Defined in: types/flags.ts:11

Controls how Codi manages a flag’s value for a given agent.

• "enforced" — value is fixed; agents cannot override it
• "enabled" — feature is on; agents may override
• "disabled" — feature is off; agents may override
• "inherited" — Codi does not set a value; the agent uses its own default
• "delegated_to_agent_default" — explicitly opt out of Codi management for this flag
• "conditional" — value depends on the conditions field (agent id or file pattern)

Result

type Result<T, E> = 
  | {
  data: T;
  ok: true;
}
  | {
  errors: E;
  ok: false;
};

Defined in: types/result.ts:22

A discriminated union representing either a successful value (ok: true) or a list of errors (ok: false).

Use ok() and err() to construct results. Use isOk() and isErr() as type guards to narrow the union safely.

Type Parameters

Example

import { ok, err, isOk } from 'codi-cli';

const result: Result<string> = someOperation();
if (isOk(result)) {
  console.log(result.data); // typed as string
} else {
  result.errors.forEach(e => console.error(e.message));
}

Functions

err()

function err<E>(errors): Result<never, E>;

Defined in: types/result.ts:50

Wraps one or more errors in a failed Result.

Type Parameters

Parameters

Returns

Result<never, E>

A Result with ok: false and the given errors

Example

return err([createError('E_CONFIG_NOT_FOUND', { path })]);

isErr()

function isErr<T, E>(result): result is { errors: E; ok: false };

Defined in: types/result.ts:70

Type guard that narrows a Result to its failure variant.

Type Parameters

Parameters

Returns

result is { errors: E; ok: false }

true if the result failed; narrows type to { ok: false; errors: E }

isOk()

function isOk<T, E>(result): result is { data: T; ok: true };

Defined in: types/result.ts:60

Type guard that narrows a Result to its success variant.

Type Parameters

Parameters

Returns

result is { data: T; ok: true }

true if the result is successful; narrows type to { ok: true; data: T }

ok()

function ok<T>(data): Result<T>;

Defined in: types/result.ts:35

Wraps a value in a successful Result.

Type Parameters

Parameters

Returns

Result<T>

A Result with ok: true and the given data

Example

return ok({ name: 'my-rule', content: '...' });