CodiLay — CLI Reference & Docs

Opens an interactive chat session. Three escalation layers: doc-based (instant), deep source reading (when doc can't answer), and a learning loop that patches the doc with new answers.

EXAMPLES

$codilay chat .# start chat for current directory

$codilay chat ./my-project

codilay search . "query"

CHAT

Full-text search across all past conversations

TF-IDF inverted index search across every past chat session for the project. Finds that retry logic discussion from two weeks ago in milliseconds.

FLAGS

--top NReturn top N results (default: 10)

--role assistant|userFilter by message role

-c <id>Restrict search to a specific conversation ID

--rebuildRebuild the search index before querying

EXAMPLES

$codilay search . "authentication flow"

$codilay search . "error handling" --top 5 --role assistant

$codilay search . "database migration" -c <conversation-id>

$codilay search . "query" --rebuild# rebuild index first

## web-ui

web-ui

codilay serve .

WEB-UI

Launch the Web UI

Starts the FastAPI server and opens the 3-layer web documentation browser: Reader (static, no LLM), Chatbot (doc context), and Deep Agent (reads source when needed).

EXAMPLES

$codilay serve .# serve current directory docs

$codilay serve ./my-project

## watch

watch

codilay watch .

WATCH

Watch for file changes, auto-update docs

Runs CodiLay as a background daemon. Listens for filesystem events via watchdog and triggers incremental re-runs on save. Debounced to avoid redundant work.

FLAGS

--debounce NDebounce delay in seconds (default: 3)

-vVerbose output for debugging

EXAMPLES

$codilay watch .# watch current directory

$codilay watch . --debounce 5# 5-second debounce

$codilay watch . -v# verbose output

## export

export

codilay export .

EXPORT

Export docs in AI-friendly format

Produces a compressed, token-efficient export of your documentation for feeding into another LLM's context window. Supports markdown, XML, and JSON with optional token budgets.

FLAGS

--format markdown|xml|jsonOutput format (default: markdown)

--max-tokens NCap the output at N tokens

--no-graphExclude the dependency graph from the export

-o <file>Write output to a file instead of stdout

EXAMPLES

$codilay export .# compact markdown (default)

$codilay export . --format xml --max-tokens 4000

$codilay export . -f json --no-graph -o context.json

codilay diff-doc .

EXPORT

Show section-level documentation diff between runs

Compares the current documentation against the snapshot from the previous run, showing exactly which sections were added, removed, or modified. Snapshots are saved automatically after every run.

FLAGS

--json-outputOutput diff as JSON for programmatic use

EXAMPLES

$codilay diff-doc .# show doc changes since last run

$codilay diff-doc . --json-output

## graph

graph

codilay graph .

GRAPH

View and filter the dependency graph

Renders and filters the full wire dependency graph. Slice by wire type, file layer, module, connection count, or direction to surface architectural hubs and reduce noise on large repos.

FLAGS

--wire-type import|call|refFilter to a specific wire type

--layer <path>Filter to a specific directory layer

--min-connections NShow only nodes with N+ connections

--direction incoming|outgoing|bothFilter edge direction

-x <glob>Exclude files matching a glob pattern

--list-filtersList all available filter values

--json-outputOutput as JSON

EXAMPLES

$codilay graph . --wire-type import

$codilay graph . --layer src/api

$codilay graph . --min-connections 3 --direction outgoing

$codilay graph . -w import -l src/core -x "tests/**"

$codilay graph . --list-filters

$codilay graph . --json-output

## triage

triage

codilay triage-feedback add

TRIAGE

Flag an incorrect triage decision

Record a correction for a file or glob pattern that was mis-classified during triage. Corrections are stored per-project and automatically injected into future triage prompts.

FLAGS

. <file> <from> <to>Project path, file, current tier, correct tier

-r <reason>Reason for the correction

--patternTreat the file argument as a glob pattern

EXAMPLES

$codilay triage-feedback add . src/auth/handler.py skim core -r "Contains critical auth logic"

$codilay triage-feedback add . "tests/**" core skip --pattern -r "Tests should be skipped"

codilay triage-feedback list

TRIAGE

List all stored triage corrections

Shows all recorded triage corrections for the project.

EXAMPLES

$codilay triage-feedback list .

codilay triage-feedback hint

TRIAGE

Set a project-type hint for triage

Attaches a free-text hint to a project type (e.g. react, django) that is injected into the triage prompt to guide classification.

EXAMPLES

$codilay triage-feedback hint . react "Treat all hooks/ files as core"

codilay triage-feedback remove

TRIAGE

Remove feedback for a specific file

Deletes a stored triage correction for a specific file path.

EXAMPLES

$codilay triage-feedback remove . src/auth/handler.py

codilay triage-feedback clear

TRIAGE

Clear all triage feedback

Wipes all stored triage corrections for the project. Requires --yes confirmation flag.

EXAMPLES

$codilay triage-feedback clear . --yes

## team

team

codilay team add-user

TEAM

Add a team member

Registers a team member in the project's shared knowledge base. Used to attribute facts, decisions, and annotations.

EXAMPLES

$codilay team add-user . alice --display-name "Alice Chen"

codilay team add-fact

TEAM

Record a team fact

Stores a shared fact about the project. Facts are injected into LLM context during documentation and chat sessions.

FLAGS

-c <category>Category (e.g. architecture, infra, api)

-a <user>Author (team member username)

-t <tag>Tag(s) for filtering (repeatable)

EXAMPLES

$codilay team add-fact . "We use Celery for async tasks" -c architecture -a alice -t backend -t infra

codilay team add-decision

TEAM

Record an architectural decision

Logs an architectural decision record (ADR) with rationale. Surfaced to the AI during documentation runs.

FLAGS

-a <user>Author (team member username)

-f <file>Associated file path

EXAMPLES

$codilay team add-decision . "Use PostgreSQL over MySQL" "Better JSON support, needed for our schema" -a alice -f src/db/

codilay team add-convention

TEAM

Add a coding convention

Records a coding convention that the AI will respect when generating documentation and answering chat questions.

FLAGS

-e <example>JSON example of the convention

-a <user>Author

EXAMPLES

codilay team add-convention . "Error Handling" "All API endpoints must return structured error responses" -e '{"error": "message", "code": 400}' -a alice

codilay team annotate

TEAM

Annotate a specific file

Attaches a team note to a specific file, optionally scoped to a line range. Visible to the AI when processing that file.

FLAGS

-a <user>Author

-l <start>-<end>Line range (e.g. 1-50)

EXAMPLES

$codilay team annotate . src/api/routes.py "This file is getting too large, plan to split by domain" -a alice -l 1-50

codilay team facts / decisions / conventions / annotations / users

TEAM

List team knowledge

List stored facts, decisions, conventions, file annotations, or team members. All support filtering flags.

FLAGS

-c <category>Filter facts by category

-s active|supersededFilter decisions by status

-f <file>Filter annotations by file

EXAMPLES

$codilay team facts .# all facts

$codilay team facts . -c architecture

$codilay team decisions . -s active

$codilay team conventions .

$codilay team annotations . -f src/api/routes.py

$codilay team users .

codilay team vote

TEAM

Vote on a fact

Upvote or downvote a stored fact by its ID. Vote scores are surfaced to the AI to indicate community confidence.

EXAMPLES

$codilay team vote . <fact-id> up

## schedule

schedule

codilay schedule set

SCHEDULE

Configure a doc update schedule

Sets up automatic documentation re-runs triggered by a cron expression, new commits on a branch, or both. Runs as a background daemon with PID file management.

FLAGS

--cron <expr>Cron expression (e.g. "0 2 * * *" for 2am daily)

--on-commitTrigger on every new commit

--branch <name>Branch to watch (default: main)

EXAMPLES

$codilay schedule set . --cron "0 2 * * *"# daily at 2am

$codilay schedule set . --on-commit --branch main

$codilay schedule set . --cron "0 2 * * *" --on-commit# both triggers

codilay schedule start

SCHEDULE

Start the scheduler

Starts the configured scheduler in the foreground.

FLAGS

-vVerbose logging

EXAMPLES

$codilay schedule start .

$codilay schedule start . -v

codilay schedule stop

SCHEDULE

Stop a running scheduler

Stops the running scheduler daemon for the project.

EXAMPLES

$codilay schedule stop .

codilay schedule status

SCHEDULE

Check current schedule

Displays the current schedule configuration and daemon status.

EXAMPLES

$codilay schedule status .

codilay schedule disable

SCHEDULE

Disable the schedule

Disables the schedule without deleting it. Re-enable with schedule set.

EXAMPLES

$codilay schedule disable .

## config

codilay.config.json

// place in your project root. all fields are optional — CodiLay works without it.

codilay.config.json

{
  "ignore": ["dist/**", "**/tests/**"],
  "notes": "This is a React/Next.js frontend using Tailwind.",
  "instructions": "Focus on data-fetching patterns and state management.",
  "llm": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-latest"
  }
}

FIELD

TYPE

DESCRIPTION

ignore

string[]

Glob patterns for files to exclude from scanning. Merged with .gitignore.

e.g. ["dist/**", "**/tests/**"]

notes

string

Free-text notes about the project. Injected into the LLM's system prompt on every run.

e.g. "This is a React/Next.js frontend using Tailwind."

instructions

string

Specific documentation instructions for the agent — what to emphasize, what to skip.

e.g. "Focus on data-fetching patterns and state management."

llm.provider

string

LLM provider to use for this project. Overrides global setup. Options: anthropic, openai, google, ollama, groq, deepseek, mistral, llama-cloud, or any OpenAI-compatible endpoint.

e.g. "anthropic"

llm.model

string

Specific model to use. Must be valid for the configured provider.

e.g. "claude-3-5-sonnet-latest"

## providers

Multi-provider support

// CodiLay is provider-agnostic. configure globally via codilay setup or per-project via codilay.config.json.

PROVIDER

TYPE

MODELS

Anthropic

CLOUD

claude-3-5-sonnet-latest, claude-3-haiku-...

OpenAI

CLOUD

gpt-4o, gpt-4o-mini, o1, ...

Google Gemini

CLOUD

gemini-1.5-pro, gemini-flash, ...

Ollama

LOCAL

llama3, mistral, codellama, ...

Groq

LOCAL

llama3-70b-8192, mixtral-8x7b, ...

DeepSeek

CLOUD

deepseek-coder, deepseek-chat

Mistral

CLOUD

mistral-large, codestral, ...

Llama Cloud

CLOUD

llama-3.1-70b-instruct, ...

OpenAI-compatible

CUSTOM

Any endpoint with /v1/chat/completions

## project-structure

Source layout

// all source lives under src/codilay/.

src/codilay/

cli.py# Command parsing & Interactive Menu

scanner.py# Git-aware file walking

triage.py# AI-powered file categorization

processor.py# The Agent Loop & large file chunking

wire_manager.py# Linkage & dependency resolution

docstore.py# Living CODEBASE.md management

chatstore.py# Persistent memory & chat history

server.py# FastAPI Intelligence Server (Web UI + API)

watcher.py# File system watcher (watch mode)

exporter.py# AI-friendly doc export (markdown/xml/json)

doc_differ.py# Section-level doc diffing & version snapshots

triage_feedback.py# Triage correction store & feedback loop

graph_filter.py# Dependency graph filtering engine

team_memory.py# Shared team knowledge base

search.py# Full-text conversation search (inverted index)

scheduler.py# Cron & commit-based auto re-runs

web/# Premium web frontend

vscode-extension/EXT

package.json# Extension manifest

tsconfig.json# TypeScript config

src/extension.ts# Extension entry point — sidebar, webview, decorations, commands