ECA - Editor Code Assistant

ECA AI coding agent configuration file

Type object
File match **/eca/config.json **/.eca/config.json
Schema URL https://catalog.lintel.tools/schemas/schemastore/eca-editor-code-assistant/latest.json
Source https://eca.dev/config.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Configuration schema for ECA (Editor Code Assistant). See https://eca.dev/config/introduction for full documentation.

Properties

$schema string

JSON Schema reference for editor validation support.

providers Record<string, object>

LLM provider configurations. Each key is the provider name.

defaultModel string | null

Default model in format 'provider/model'. When null, ECA decides the default model.

Examples: "anthropic/claude-sonnet-4-6", "openai/gpt-5.2"
defaultAgent string

The default agent to use for new chats.

Default: "code"
Examples: "code", "plan"
chatRetentionDays integer

Number of days to keep old chats and tool call output cache before cleanup. Set to 0 to disable cleanup entirely.

Default: 14
agent Record<string, object>

Named agent configurations for different workflows.

defaultBehavior string

Deprecated: use 'defaultAgent' instead. Backward compatible alias.

Examples: "code", "plan"
behavior Record<string, object>

Deprecated: use 'agent' instead. Backward compatible alias.

hooks Record<string, object>

Shell actions that run before or after specific events.

rules object[]

Rules are contexts passed to the LLM during a prompt, useful to tune prompts or LLM responses.

disabledTools string[]

List of tool names to disable globally.

commands object[]

Custom command prompt files.

customTools Record<string, object>

User-defined command-line tools the LLM can use.

toolCall object

Tool call configuration including approval rules and tool-specific settings.

4 nested properties
approval object

Tool approval configuration.

4 nested properties
byDefault string

Default approval mode for tools not explicitly configured.

Default: "ask"
Values: "ask" "allow" "deny"
allow Record<string, object>

Tools that are automatically allowed. Key is tool or server name.

ask Record<string, object>

Tools that require user approval. Key is tool or server name.

deny Record<string, object>

Tools that are denied. Key is tool or server name.

readFile object

Configuration for the read_file tool.

1 nested properties
maxLines integer

Maximum number of lines returned by read_file.

Default: 2000
shellCommand object

Configuration for the shell_command tool.

3 nested properties
path string

Custom shell executable path. Overrides the default platform shell (bash on Linux/macOS, powershell on Windows).

args string[]

Arguments passed to the shell before the script argument. E.g. ["-l", "-c"] for bash.

summaryMaxLength integer

Maximum length of shell command summary.

Default: 25
outputTruncation object

Output truncation settings for tool results.

2 nested properties
lines integer

Maximum number of lines in tool output.

Default: 2000
sizeKb integer

Maximum size in kilobytes for tool output.

Default: 50
mcpTimeoutSeconds integer

Timeout in seconds for MCP server operations.

Default: 60
lspTimeoutSeconds integer

Timeout in seconds for LSP operations.

Default: 30
streamIdleTimeoutSeconds integer

Timeout in seconds to wait without receiving data before considering a LLM stream stalled.

Default: 120
mcpServers Record<string, object>

MCP (Model Context Protocol) server configurations.

prompts object

Custom prompt configurations. Values support dynamic strings like ${file:path} and ${classpath:path}.

8 nested properties
chat string

System prompt for chat interactions.

chatTitle string

Prompt for generating chat titles.

compact string

Prompt for compacting chat context.

init string

Prompt for the /init command.

skillCreate string

Prompt for skill creation.

completion string

System prompt for inline completions.

rewrite string

System prompt for rewrites.

tools Record<string, string>

Custom descriptions for specific tools. Key is the tool name.

welcomeMessage string

Custom welcome message shown when ECA starts.

autoCompactPercentage integer

Context window usage percentage at which auto-compact triggers.

Default: 75
min=0max=100
index object

Indexing configuration for workspace files.

2 nested properties
ignoreFiles object[]
repoMap object

Repository map configuration for context building.

2 nested properties
maxTotalEntries integer

Maximum total entries in the repo map.

Default: 800
maxEntriesPerDir integer

Maximum entries per directory in the repo map.

Default: 50
completion object

Inline completion configuration.

1 nested properties
model string

Model to use for inline completions.

Default: "openai/gpt-4.1"
Examples: "openai/gpt-4.1", "github-copilot/gpt-4.1"
rewrite object

Rewrite feature configuration.

1 nested properties
model string

Model to use for rewrites. Defaults to the same model selection as chat.

Examples: "openai/gpt-4.1", "github-copilot/gpt-4.1"
variantsByModel Record<string, object>

Built-in variant definitions keyed by model-name regex pattern.

otlp Record<string, string>

OpenTelemetry OTLP collector configuration. Keys follow otlp auto-configure settings.

netrcFile string | null

Path to a custom netrc credential file. When null, searches ~/.netrc or ~/_netrc.

Default: null
chat object

Chat feature settings.

1 nested properties
title boolean

Whether to automatically generate a title for new chats.

Default: true
plugins Record<string, object | string[]>

Plugin system for loading external configuration from git repos or local paths. Each key (except install) is a named plugin source with a source URL or path. install lists plugin names to install from any registered source.

Examples: {"my-org":{"source":"https://github.com/org/ai-plugins.git"},"install":["plugin-a","plugin-b"]}
1 nested properties
install string[]

List of plugin names to install from registered sources.

remote object

Remote web control server configuration. When enabled, starts an embedded HTTP server allowing a web frontend (web.eca.dev) to observe and control chat sessions in real-time.

4 nested properties
enabled boolean

Enables the remote HTTP server.

host string

Host used in the logged URL for web.eca.dev to connect back to. Can be a LAN IP, public IP, domain, or tunnel URL. When unset, auto-detected via InetAddress/getLocalHost.

Examples: "192.168.1.42", "myserver.example.com"
port integer

Port the HTTP server listens on. When unset, tries port 7777, then 7778, 7779, etc. up to 20 attempts.

Examples: 7777
password string

Auth token for Bearer authentication. When unset, a 32-byte hex token is auto-generated and logged to stderr.

network object

Network configuration for custom CA certificates and mTLS client certificates. Values support dynamic string interpolation (e.g. ${env:SSL_CERT_FILE}).

4 nested properties
caCertFile string

Path to a PEM file containing custom CA certificates. These are added to the JVM default trust store, so public CAs remain trusted. Falls back to SSL_CERT_FILE or NODE_EXTRA_CA_CERTS environment variables.

Examples: "/etc/ssl/certs/corporate-ca.pem", "${env:SSL_CERT_FILE}"
clientCert string

Path to a PEM file containing the client certificate for mutual TLS (mTLS). Falls back to ECA_CLIENT_CERT environment variable.

Examples: "/etc/ssl/certs/client.pem", "${env:ECA_CLIENT_CERT}"
clientKey string

Path to a PEM file containing the client private key for mutual TLS (mTLS). Supports both unencrypted and encrypted PKCS8 keys. Falls back to ECA_CLIENT_KEY environment variable.

Examples: "/etc/ssl/private/client-key.pem", "${env:ECA_CLIENT_KEY}"
clientKeyPassphrase string

Passphrase for an encrypted client private key. Only needed when the key file is encrypted. Falls back to ECA_CLIENT_KEY_PASSPHRASE environment variable.

Examples: "${env:ECA_CLIENT_KEY_PASSPHRASE}"

Definitions

variantPayload object

Additional request payload fields applied when a variant is selected. Empty object ({}) can be used to remove a built-in variant override.

variantsByModelEntry object

Variant set applied when the model name matches this regex key.

variants Record<string, object>

Named variants provided for matching models.

excludeProviders string[]

Provider names for which this regex-based variant set should not apply.

provider object

Configuration for an LLM provider.

api string

The API protocol to use for this provider.

Values: "openai-responses" "openai-chat" "anthropic"
fetchModels boolean

Whether to fetch available models from the provider's API.

url string

Base URL for the provider's API. Supports dynamic strings like ${env:VAR}.

format=uri
key string | null

API key for authentication. Supports dynamic strings like ${env:MY_API_KEY}.

keyRc string

Credential file lookup in format [login@]machine[:port] for netrc-based authentication.

requiresAuth boolean

Whether this provider requires authentication.

completionUrlRelativePath string

Custom relative URL path for completion requests.

thinkTagStart string

Custom start tag for thinking/reasoning blocks in model responses.

thinkTagEnd string

Custom end tag for thinking/reasoning blocks in model responses.

httpClient string

HTTP client implementation to use.

Values: "jdk" "okhttp"
retryRules object[]

Custom retry rules. Each rule can match by HTTP status code and/or error text regex pattern. When matched, the request is retried with exponential backoff.

models Record<string, object>

Available models for this provider. Each key is the model alias.

model object

Configuration for a specific model.

modelName string

The actual model identifier sent to the API, if different from the alias key.

extraPayload object

Additional fields to include in the API request payload.

extraHeaders Record<string, string>

Additional HTTP headers to include in API requests.

reasoningHistory string

How to handle reasoning/thinking history in conversation context.

Default: "all"
Values: "all" "turn" "off"
variants Record<string, object>

Named payload presets for this model. Merged with built-in variants; same-name entries override built-ins. Setting a variant to {} removes that built-in variant.

agent object

A named agent configuration.

inherit string

Name of another agent to inherit configuration from. The current agent's settings are deep-merged on top of the inherited agent's settings.

Examples: "code", "plan", "explorer"
mode string

Agent mode. 'primary' for standalone agents, 'subagent' for agent-spawnable agents.

Values: "primary" "subagent"
description string

Description of this agent's purpose. Required for subagents — shown to the LLM so it knows when to spawn this agent. Supports dynamic strings like ${file:path} and ${classpath:path}.

systemPrompt string

System prompt for this agent. Overrides the default system prompt. Supports dynamic strings like ${file:path} and ${classpath:path}.

maxSteps integer

Maximum number of tool-call steps before the agent is halted. Useful for limiting subagent execution.

min=1
defaultModel string

Default model for this agent, overriding the global default.

Examples: "anthropic/claude-sonnet-4-6"
variant string

Default variant for this agent. Used when available for the selected model.

Examples: "medium", "high"
disabledTools string[]

Tools to disable for this agent.

autoCompactPercentage integer

Context window usage percentage at which auto-compact triggers for this agent.

min=0max=100
toolCall object

Tool call configuration including approval rules and tool-specific settings.

4 nested properties
approval object

Tool approval configuration.

4 nested properties
byDefault string

Default approval mode for tools not explicitly configured.

Default: "ask"
Values: "ask" "allow" "deny"
allow Record<string, object>

Tools that are automatically allowed. Key is tool or server name.

ask Record<string, object>

Tools that require user approval. Key is tool or server name.

deny Record<string, object>

Tools that are denied. Key is tool or server name.

readFile object

Configuration for the read_file tool.

1 nested properties
maxLines integer

Maximum number of lines returned by read_file.

Default: 2000
shellCommand object

Configuration for the shell_command tool.

3 nested properties
path string

Custom shell executable path. Overrides the default platform shell (bash on Linux/macOS, powershell on Windows).

args string[]

Arguments passed to the shell before the script argument. E.g. ["-l", "-c"] for bash.

summaryMaxLength integer

Maximum length of shell command summary.

Default: 25
outputTruncation object

Output truncation settings for tool results.

2 nested properties
lines integer

Maximum number of lines in tool output.

Default: 2000
sizeKb integer

Maximum size in kilobytes for tool output.

Default: 50
prompts object

Custom prompt configurations. Values support dynamic strings like ${file:path} and ${classpath:path}.

8 nested properties
chat string

System prompt for chat interactions.

chatTitle string

Prompt for generating chat titles.

compact string

Prompt for compacting chat context.

init string

Prompt for the /init command.

skillCreate string

Prompt for skill creation.

completion string

System prompt for inline completions.

rewrite string

System prompt for rewrites.

tools Record<string, string>

Custom descriptions for specific tools. Key is the tool name.

hook object

A hook configuration for running shell actions on events.

type string required

The event type that triggers this hook.

Values: "sessionStart" "sessionEnd" "chatStart" "chatEnd" "preRequest" "postRequest" "preToolCall" "postToolCall"
actions hookAction[] required

List of actions to execute when the hook triggers.

matcher string

Regex pattern for matching server__tool-name. Only for *ToolCall hook types.

visible boolean

Whether to show hook execution in chat.

Default: true
runOnError boolean

For postToolCall hooks, whether to run even if the tool errored.

Default: false
hookAction object

A shell action executed by a hook.

type string required

Action type.

Values: "shell"
shell string

Inline shell script to execute.

file string

Path to a shell script file to execute.

timeout integer

Timeout in milliseconds for this action.

Default: 30000
customTool object

A user-defined command-line tool.

description string required

Description of what the tool does. Used by the LLM to decide when to use it.

command string required

Command template with {{argument_name}} placeholders.

schema object required

Schema defining the tool's parameters.

2 nested properties
properties Record<string, object>

Parameter definitions.

required string[]

List of required parameter names.

toolCallConfig object

Tool call configuration including approval rules and tool-specific settings.

approval object

Tool approval configuration.

4 nested properties
byDefault string

Default approval mode for tools not explicitly configured.

Default: "ask"
Values: "ask" "allow" "deny"
allow Record<string, object>

Tools that are automatically allowed. Key is tool or server name.

ask Record<string, object>

Tools that require user approval. Key is tool or server name.

deny Record<string, object>

Tools that are denied. Key is tool or server name.

readFile object

Configuration for the read_file tool.

1 nested properties
maxLines integer

Maximum number of lines returned by read_file.

Default: 2000
shellCommand object

Configuration for the shell_command tool.

3 nested properties
path string

Custom shell executable path. Overrides the default platform shell (bash on Linux/macOS, powershell on Windows).

args string[]

Arguments passed to the shell before the script argument. E.g. ["-l", "-c"] for bash.

summaryMaxLength integer

Maximum length of shell command summary.

Default: 25
outputTruncation object

Output truncation settings for tool results.

2 nested properties
lines integer

Maximum number of lines in tool output.

Default: 2000
sizeKb integer

Maximum size in kilobytes for tool output.

Default: 50
approval object

Tool approval configuration.

byDefault string

Default approval mode for tools not explicitly configured.

Default: "ask"
Values: "ask" "allow" "deny"
allow Record<string, object>

Tools that are automatically allowed. Key is tool or server name.

ask Record<string, object>

Tools that require user approval. Key is tool or server name.

deny Record<string, object>

Tools that are denied. Key is tool or server name.

approvalMatcher object

Matcher configuration for a tool approval rule.

argsMatchers Record<string, string[]>

Map of argument name to list of Java regex patterns to match against.

mcpServer object

MCP server configuration. Use 'url' for remote HTTP servers or 'command' for stdio servers.

url string

URL for remote HTTP-streamable or SSE MCP servers.

format=uri
command string

Command to launch a stdio MCP server.

args string[]

Arguments for the stdio MCP server command.

env Record<string, string>

Environment variables to set for the MCP server process.

disabled boolean

Whether this MCP server is disabled.

Default: false
headers Record<string, string>

Custom HTTP headers to include in requests to this MCP server. If an Authorization header is set, OAuth is skipped entirely.

clientId string

OAuth client ID for servers that require a pre-registered OAuth application (e.g. Databricks, Slack). When set, dynamic client registration is skipped.

clientSecret string

OAuth client secret for servers that require confidential OAuth (e.g. Slack MCP). Used together with clientId for token exchange.

oauthPort integer

Fixed port for the OAuth callback server. Required by providers like Slack that mandate pre-registered redirect URIs. When set, the callback uses HTTPS with a bundled localhost certificate. Register https://localhost:<port>/auth/callback as the redirect URI in your OAuth app.

min=1max=65535
prompts object

Custom prompt configurations. Values support dynamic strings like ${file:path} and ${classpath:path}.

chat string

System prompt for chat interactions.

chatTitle string

Prompt for generating chat titles.

compact string

Prompt for compacting chat context.

init string

Prompt for the /init command.

skillCreate string

Prompt for skill creation.

completion string

System prompt for inline completions.

rewrite string

System prompt for rewrites.

tools Record<string, string>

Custom descriptions for specific tools. Key is the tool name.