Customization

Codanna is a local code intelligence MCP server and CLI for AI coding agents. Configuration lives in .codanna/settings.toml — embedding model, indexed paths, language resolvers, logging, and guidance templates.

Directory Structure

.codanna/
├── settings.toml     # Main configuration
├── index/            # Index storage
└── .project-id       # Project identifier

.codannaignore

Codanna respects .gitignore and adds its own .codannaignore:

# Created by codanna init
.codanna/       # Don't index own data
target/         # Skip build artifacts
node_modules/   # Skip dependencies

Semantic Search

Local Models

[semantic_search]
model = "AllMiniLML6V2"

Model	Description
`AllMiniLML6V2`	English-optimized (default)
`MultilingualE5Small`	94 languages, 384 dimensions
`MultilingualE5Base`	94 languages, 768 dimensions

Remote Embedding Backend

Use an OpenAI-compatible HTTP server instead of local models:

[semantic_search]
remote_url = "http://localhost:11434"
remote_model = "nomic-embed-text"
remote_dim = 768

Or override via environment variables (take precedence over config):

Variable	Description
`CODANNA_EMBED_URL`	Server base URL (enables remote mode)
`CODANNA_EMBED_MODEL`	Model name to send to the server
`CODANNA_EMBED_DIM`	Expected output dimension
`CODANNA_EMBED_API_KEY`	Bearer auth token (env var only, not stored in config)

See Semantic Search for provider examples and migration details.

Changing Models

Switching between local models or between local and remote requires re-indexing:

codanna index --force

Indexed Paths

[indexing]
indexed_paths = [
    "/path/to/project1",
    "/path/to/project2"
]

Manage via CLI:

codanna add-dir src
codanna list-dirs
codanna remove-dir old-project

Language Configuration

Project resolution reads build configuration files to determine source roots and module paths. This enables:

Correct module path generation (e.g., org.example.service for Java, Core for Swift)
Path alias resolution (e.g., @app/* in TypeScript)
Cross-package relationship tracking

Resolution rules are cached in .codanna/index/resolvers/. The cache rebuilds during codanna index when config file contents change (SHA-based invalidation). See Project Resolvers for configuration details for all 8 supported languages.

TypeScript

[languages.typescript]
enabled = true
config_files = [
    "tsconfig.json",
    "packages/web/tsconfig.json"
]

Reads tsconfig.json to resolve path aliases like @app/* and baseUrl settings.

Function wrappers

Many TypeScript codebases define functions through higher-order wrappers: const View = memo(() => {}), const Input = forwardRef((props, ref) => {}), const load = wrap("load")(function* () {}). By default the parser records these bindings as constants because the value is a call expression, so they carry no call graph. Declare the wrapper callee names to register such bindings as functions and index the wrapped body:

[languages.typescript.parser_options]
function_wrappers = ["memo", "forwardRef", "Effect.gen", "Effect.fn"]

A declared name matches a member expression’s full dotted text (Effect.gen matches Effect.gen(...) only) or its final property name (memo matches both memo(...) and React.memo(...)). Curried chains (Effect.fn("name")(fn)) resolve through the innermost callee.
Calls inside the wrapped body attribute to the binding, so find_callers, get_calls, and analyze_impact cover wrapper-defined functions.
The list is empty by default; indexing behavior is unchanged until you declare names.
After editing the list, run codanna index --force — changing parser options changes what the index contains, and the emission gate does not detect configuration edits.

A value that is not an array of strings fails codanna index with an error naming this key.

Java

[languages.java]
enabled = true
config_files = ["pom.xml"]

# For multi-module projects with custom layouts:
[[languages.java.projects]]
config_file = "service/build.gradle"
source_layout = "jvm"  # jvm | standard-kmp | flat-kmp

Reads Maven pom.xml or Gradle build.gradle to detect source roots (src/main/java, src/test/java). Generates module paths like org.springframework.samples.petclinic.owner.

Swift

[languages.swift]
enabled = true
config_files = [
    "Package.swift",
    "modules/networking/Package.swift"
]

Reads Swift Package Manager Package.swift to detect source roots. Uses SPM conventions (Sources/, Tests/) or custom path: specifications. Generates module paths like Networking, Cache, General.

Logging

[logging]
default = "warn"

[logging.modules]
cli = "debug"
indexing = "info"

Or via environment:

RUST_LOG=debug codanna index

View Configuration

codanna config

Reference

Directory Structure

.codannaignore

Semantic Search

Local Models

Remote Embedding Backend

Changing Models

Indexed Paths

Language Configuration

TypeScript

Function wrappers

Java

Swift

Logging

View Configuration

Next Steps

Project Resolvers

Debugging

​Directory Structure

​.codannaignore

​Semantic Search

​Local Models

​Remote Embedding Backend

​Changing Models

​Indexed Paths

​Language Configuration

​TypeScript

​Function wrappers

​Java

​Swift

​Logging

​View Configuration

​Next Steps

Project Resolvers

Debugging

Directory Structure

.codannaignore

Semantic Search

Local Models

Remote Embedding Backend

Changing Models

Indexed Paths

Language Configuration

TypeScript

Function wrappers

Java

Swift

Logging

View Configuration

Next Steps