Skip to content

Commands

Run uncoded from the project's environment with uv run uncoded.

To… Use
Set uncoded up in a project uv run uncoded init
Build or refresh the index and skills uv run uncoded sync
Check generated files without writing uv run uncoded check
Read a Python symbol's definition uv run uncoded body <name_path> --in <file>
Find references to a Python symbol uv run uncoded refs <name_path> --in <file>
Print the installed version uv run uncoded --version

Every command but init and --version runs inside a project. It finds the configuration file in the current directory or the nearest directory above it. If there is none, it exits with status 1.

usage: uncoded [-h] [--version] {init,sync,check,body,refs} ...

Build an index of a codebase for AI coding agents.

positional arguments:
  {init,sync,check,body,refs}
    init                Set uncoded up in a project, then build its index and
                        skills.
    sync                Build or refresh the index and the skills.
    check               Verify that the generated files are current, without
                        writing. Exits non-zero if any file would change.
    body                Print the definition of a named symbol to stdout.
    refs                Find all references to a named symbol and print them
                        to stdout.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

init

usage: uncoded init [-h]

options:
  -h, --help  show this help message and exit
uv run uncoded init

Sets uncoded up in the project, then runs sync. Run it in the directory that is to be the project directory.

If no configuration file is found in that directory or above it, init appends a [tool.uncoded] table to the pyproject.toml in that directory. Its source roots are whichever of src and tests exist, and its doc roots are whichever of README.md, AGENTS.md and docs exist. If pyproject.toml does not exist, or if none of those roots exist, init writes nothing and exits with status 1. If init cannot write the configuration file, it says why and exits with status 1. A configuration file that init finds is left as it is.

If sync fails, init stops there with exit status 1. After sync, init says which files to commit, and prints the lines to add to AGENTS.md or CLAUDE.md that tell agents to load the navigation skills. It does not edit those files. Running it again does no harm.

sync

usage: uncoded sync [-h]

options:
  -h, --help  show this help message and exit
uv run uncoded sync

Builds or refreshes the index and the skills. Output lists files created, updated, or removed. Running it from a subdirectory writes the same files, in the project directory.

Files that cannot be parsed or decoded are skipped with a warning, and the output ends with a line that says how many files were skipped. A skipped file does not change the exit status. Invalid configuration or roots, or a generated file that cannot be read, written or removed, cause exit status 1.

check

usage: uncoded check [-h]

options:
  -h, --help  show this help message and exit
uv run uncoded check

Runs the same pipeline as sync without changing files.

Status Meaning
0 All generated files are current.
1 A file would be created, updated, or removed, the configuration is invalid, or a generated file cannot be read.

The index is never committed, so in a fresh checkout check always reports it as stale. It is not a check for CI. See Keep the index current.

body

usage: uncoded body [-h] --in PATH name_path

positional arguments:
  name_path   Name path: one segment for top-level, two for Class/member.

options:
  -h, --help  show this help message and exit
  --in PATH   Source file path (relative to current directory).
uv run uncoded body greet --in src/greetings.py
uv run uncoded body Greeter/greet --in src/greetings.py

Prints the named symbol's source to standard output, exactly as written in the file. These examples assume a greet function or a Greeter.greet method in src/greetings.py.

Use one name for a top-level function, class, module assignment, or Python 3.12 type statement. Use Class/member for a method, property or assignment in a class body. Deeper paths and empty segments are unsupported.

The --in path is relative to the current directory, not the configuration file. It must be inside the project directory, once symbolic links are resolved. Run body from the project directory, so that the namespace map's paths can be passed to --in unchanged.

refs

usage: uncoded refs [-h] --in PATH name_path

positional arguments:
  name_path   Name path: one segment for top-level, two for Class/member.

options:
  -h, --help  show this help message and exit
  --in PATH   Source file path (relative to current directory).
uv run uncoded refs greet --in src/greetings.py
uv run uncoded refs Greeter/greet --in src/greetings.py

Finds every reference to the symbol: its definition, each import of it, and each use of it. Names and --in paths follow the same rules as body. Each result is printed as:

path:line:column

Positions are one-based. Results are sorted by path and position. Paths within the current directory are relative; other paths are absolute. Every path uses / to separate directories, on Windows too.

Reference resolution uses the pinned ty language server through uvx. The first call may download it. uvx must be on PATH.

--version

uv run uncoded --version

Prints uncoded and the installed version, such as uncoded <version>.

Lookup errors

body and refs exit with status 1 if the --in file is outside the project directory, the source cannot be read or parsed, the symbol is missing, or its name path is unsupported. refs also exits with status 1 if ty fails, and passes on what ty and uvx wrote about why. Missing required arguments exit with status 2.