Getting Started¶

Install the published package¶

For normal use, install Codira from PyPI into a dedicated host environment, separate from the repository you want to analyze. This is the simplest path when you only need to use codira and do not need unreleased plugins or features:

source .venv/bin/activate
pip install codira-bundle-official

That installs codira, the first-party analyzer plugins and backends. To add the optional FAISS similarity index, install pip install "codira-bundle-official[faiss]"; core exact similarity remains available without it.

The analyzers currently available are:

Bash, C, C++, Go, JavaScript, TypeScript, JSON, Markdown, Python, Rust, and plain text

the last two being used to analyze doccumentation, while the backend plugins are:

SQLite
DuckDB

Prefer this published install path over an editable checkout unless you are developing Codira itself, testing unreleased first-party plugins, or validating changes from a development branch.

Verify the install:

codira -V
codira plugins

For a core-only install:

pip install codira

The core-only package installs the CLI and core contracts, but it does not install the official first-party analyzer/backend bundle. Use codira-bundle-official for a ready-to-use end-user installation.

Bootstrap this repository¶

Create the local development environment cloning from github and install the repo-local Git configuration:

git clone https://github.com/marco0560/codira
python3 scripts/bootstrap_dev_environment.py

The bootstrap script installs the core package, the extracted first-party analyzer/backend packages, and the local embedding dependencies through the uv-managed repository environment. It also downloads and smoke-tests the default public ONNX embedding model required for semantic indexing.

The repository-local first-party package set is owned by:

uv run python scripts/install_first_party_packages.py \
  --include-core \
  --core-extra docs \
  --core-extra semantic

Developer automation is uv-based for dependency resolution and lockfile maintenance, while the actual checks run from the uv-managed .venv against the editable first-party package set.

Advanced compatibility mode: install into a target repository¶

Use this source-tree install path only when a local policy requires Codira in the target environment, or when you are developing Codira, testing bleeding-edge plugins, or validating unreleased features. Normal operation runs the standalone host runtime against target files; it does not execute, import, or require the target project's interpreter.

Example:

source .venv/bin/activate
uv run python ../codira/scripts/install_first_party_packages.py \
  --python "$VIRTUAL_ENV/bin/python" \
  --include-core \
  --core-extra semantic

This keeps the codira CLI available in the target repository while using the live source tree from this repository.

The current source-tree install keeps the embedding stack in the core package while the extracted first-party analyzers and backend are installed from packages/. The published end-user bundle is codira-bundle-official; while working from the current checkout, the canonical local package set is the one installed by scripts/install_first_party_packages.py.

Use codira plugins after installation if you want to verify whether a capability came from the core package, an official extracted package, or a third-party plugin.

On first indexing run, codira provisions the configured local model artifact automatically if it is missing. Model artifacts belong to the host user and can be shared by isolated Codira environments through CODIRA_MODEL_ROOT or [embeddings].model_root; they are not target-repository dependencies. If automatic provisioning cannot complete, the CLI fails with a concise remediation message.

You can still prefetch the model explicitly:

source .venv/bin/activate
uv run python ../codira/scripts/provision_embedding_model.py

Initialize Codira in a repository¶

Codira can run without a repository config file. If no explicit config exists, runtime commands use built-in defaults and create a default user-level config on first use when the platform user config directory is writable.

For a project-local setup, create a repository config:

codira config init --level repo

This writes .codira/config.toml. The config file may be committed when the repository should share analyzer selection, backend choice, or plugin settings. Normal .codira index artifacts remain local cache data and should stay ignored.

To generate the full first-party plugin configuration surface:

codira config init --level repo --full

Inspect and validate the effective configuration:

codira config dump
codira config validate
codira config explain embeddings.batch_size

Effective configuration is resolved in this order:

CLI flags
-> CODIRA_* environment variables
-> repository config: .codira/config.toml
-> user config
-> system config
-> built-in defaults

Tune embedding runtime¶

codira computes semantic embeddings through the configured local embedding engine during indexing. The default engine is sentence-transformers; an ONNX Runtime engine is also available when local ONNX model and tokenizer artifacts are configured explicitly.

Inspect the effective config:

codira config dump
codira config explain embeddings.batch_size

Create an explicit profile:

codira config init --profile low-memory
codira config init --level repo --profile gpu

Inspect candidate model/engine entries and print a config snippet:

uv run python ../codira/scripts/embedding_model_manifest.py --list
uv run python ../codira/scripts/embedding_model_manifest.py \
  --id bge-small-en-v1.5-onnx \
  --print-config

Operators can still tune one process with environment variables. These values override config files:

Variable	Meaning
`CODIRA_EMBED_BATCH_SIZE`	Batch size passed to the sentence-transformers `encode` call. Larger batches can improve full-index throughput when memory is sufficient.
`CODIRA_EMBED_DEVICE`	Device string passed to sentence-transformers. The default is `cpu`; use another value only when the local PyTorch and model environment supports it.
`CODIRA_TORCH_NUM_THREADS`	Optional intra-op PyTorch thread count, applied with `torch.set_num_threads`. This controls CPU parallelism inside individual Torch operations.
`CODIRA_TORCH_NUM_INTEROP_THREADS`	Optional inter-op PyTorch thread count, applied with `torch.set_num_interop_threads`. This controls scheduling parallelism across independent Torch operations.

Unset CODIRA_TORCH_* values leave PyTorch defaults unchanged. Invalid integer values fail fast before embedding inference. These variables change runtime scheduling only; they do not change indexed symbols, embedding payloads, or query semantics.

Optional FAISS/HNSW similarity search¶

The generated version-2 configuration starts with the always-available exact index. After installing the FAISS package, select it with embeddings.similarity_index = "faiss". Choose index_type = "flat" for FAISS exact search or "hnsw" for approximate graph search. HNSW's M and efConstruction construct the artifact; ef_search, candidate_limit, and result limits live in named embeddings.similarity_profiles entries.

ef_search means graph exploration breadth, not a fuzzy score setting. Candidate limits occur before a prefix or structural filter; result limits occur after it. Rebuild after HNSW build-setting changes:

codira emb rebuild
codira emb --search-profile default "where is plugin discovery?"

Changing only a profile does not rebuild. Changing to an incompatible persisted format requires codira emb reset followed by indexing. Version-1 configs are not migrated: regenerate with codira config init --force, then select similarity_index explicitly.

Authenticated remote Qdrant similarity search¶

The official bundle includes Qdrant but keeps exact as the default selected index. To opt in, configure a remote HTTPS endpoint, mandatory namespace, and an API-key environment variable (with an optional private-file fallback), then run codira emb rebuild. REST is default; gRPC is explicit. Qdrant retains two immutable revisions behind a stable alias and has no fallback when selected.

Use codira emb similarity-purge to inspect remote derived artifacts before adding --yes. codira emb reset --yes delegates cleanup to the selected similarity-index plugin and fails when that plugin cannot verify its owned remote state. See the package README for the full configuration and credential-file requirements.

First commands¶

Build or refresh the repository-local index:

codira index

Inspect exact symbol data:

codira sym build_parser
codira sym build_parser --json

Inspect context retrieval:

codira ctx "schema migration rules"
codira ctx "missing numpy docstring" --json

Inspect bounded graph traversal and optional DOT export:

codira calls build_parser --tree
codira calls build_parser --tree --dot
codira refs _retrieve_script_candidates --incoming --tree
codira refs _retrieve_script_candidates --incoming --tree --dot

Validation surface¶

The repository expects contributors to run:

uv run python scripts/validate_repo.py

Run Python-facing tools through scripts/validate_repo.py or scripts/run_repo_tool.py so tool cache and temporary state stays outside the repository cleanup surface.