Coador

Coador

Give AI agents a map of your Android project before they start reading the code.

Coador scans an Android repository locally and deterministically - without an LLM - and builds a structured, evidence-backed knowledge base covering the project architecture, Gradle configuration, test infrastructure, UI selectors, CI/CD, and other high-value context.

Agents query that knowledge first, then inspect only the files required for the task.

Faster context. Less repeated discovery. Lower token usage.

Coador turns an Android repository into a local knowledge base that AI agents can query instead of repeatedly re-reading and rediscovering the entire project.

The key idea behind Coador is simple: the scanning itself does not use AI or an LLM.

Coador deterministically analyzes an Android project, extracts the information most useful for development and test automation, and stores it in a structured form: architecture signals, Gradle configuration, modules and dependencies, test infrastructure, UI selectors, deep links, CI/CD, test runners, fixtures, dependency-injection overrides, and other project-level knowledge.

As a result, an AI agent does not need to rediscover a large repository from scratch for every new task - searching for the right Gradle files, reconstructing the module structure, identifying the test framework, or figuring out how UI tests are organized.

Instead, the agent can query an already prepared knowledge base and retrieve a compact answer focused only on the part of the project it currently needs.

This reduces repeated repository discovery, lowers the amount of source code that has to enter the model context, and reduces unnecessary token consumption.

Why no AI in the scanner?

Coador deliberately separates fact extraction from AI interpretation.

The repository is scanned locally by specialized deterministic detectors. They do not generate architectural descriptions and do not try to guess how the project is designed. Coador records only signals that can be supported by source files, Gradle configuration, or repository structure.

For example, instead of claiming:

This project uses Clean Architecture.

Coador may report:

domain, data, and feature modules were found, together with the observed dependencies between them.

The agent receives evidence rather than a pre-generated interpretation and can reason about that evidence itself.

Whenever possible, Coador also preserves the provenance of each finding: the source file and exact source lines, a file-level observation, or a value obtained from the configured Gradle model.

How it works

Coador scans an Android repository and builds a structured local profile of the project. The analysis covers nine main areas:

The complete catalogue currently contains 84 detectors and is generated in docs/detectors.md.

The resulting knowledge is stored locally and can be consumed both by developers and by AI tools. Developers get a CLI and human-readable Markdown views. AI agents get an MCP interface for reading the project overview, searching for information, and retrieving individual sections with supporting evidence.

Android repository
        ↓
Coador scan
        ↓
structured local knowledge base
        ↓
AI agent queries only the information it needs
        ↓
agent opens specific source files only when required

Coador produces two kinds of findings. A signal reports an observed capability and samples its evidence. An inventory retains collected values such as deep links, exported components and literal UI test selectors. Inventories declare whether they are complete, incomplete or unknown within their documented collection boundary.

The default scan reads repository text and needs no Android toolchain. An optional --gradle pass asks a trusted project's configured build for facts that static text cannot resolve, such as variants declared by convention plugins. Every section says whether its source is heuristic or gradle.

Practical example

Suppose an AI agent needs to add a new Android UI test.

Without Coador, the agent may first need to discover:

• where instrumentation tests are located;
• which test runner is used;
• whether a shared base test exists;
• how screen objects or robots are structured;
• whether the project uses Espresso, Kaspresso, or Compose testing;
• how authentication is handled in tests;
• which selectors already exist;
• whether test DI or fake dependencies are available;
• how the test is executed locally and in CI.

In a large repository, answering these questions can require inspecting dozens of files before the actual task even begins.

With Coador, much of that information has already been collected and structured. The agent can query only the test infrastructure, selectors, or CI configuration it needs and then open a small number of specific source files required for the implementation.

For example, connect an agent to the recorded Now in Android revision and ask:

You: How do I add and run an instrumentation UI test in this project?

Agent: Put the test beside the existing app tests under app/src/androidTest. Follow their Hilt/Compose setup: @HiltAndroidTest, HiltAndroidRule first, then createAndroidComposeRule<MainActivity>(). The app selects NiaTestRunner, which starts HiltTestApplication. Shared fakes replace production bindings through @TestInstallIn. CI runs the observed task ./gradlew connectedDemoDebugAndroidTest. That task is a source-backed reference, not a complete Gradle task enumeration.

The answer is compact, but each claim remains connected to evidence that the agent or developer can inspect.

Local and verifiable

By default, Coador works locally. Its standard analysis does not require:

• an LLM;
• an embedding model;
• a vector database;
• an external API;
• Docker;
• uploading repository source code to an external service.

The generated project profile is deterministic: the same repository state and scan configuration are expected to produce the same structured result. This makes the knowledge base suitable for keeping alongside the project, updating it with the codebase, and reviewing its changes like any other generated project artifact.

profile.json is the machine-readable source of truth. Markdown layers are a human projection of that profile. Exact source evidence contains repository-relative paths, one-based ranges and a snapshot digest. File-level and Gradle-model findings use their own provenance forms without fabricated line numbers.

Generated source-derived fields pass through shared sanitization for common secrets, but sanitization is not a guarantee that private output is safe to publish. Review a generated knowledge base before sharing it. The full trust boundary is documented in SECURITY.md.

Coador collects no telemetry from scanned projects. Its default scan does not access the network. Package installation and the explicitly requested Gradle pass have their own network and trust boundaries.

Not a replacement for source code

Coador does not try to eliminate source-code inspection by AI agents. Its purpose is to eliminate repeated broad repository discovery.

When an agent needs to modify a particular feature, it still opens the relevant production and test files. What it no longer needs to do is repeatedly reconstruct the overall architecture, test infrastructure, Gradle setup, and CI workflow from scratch.

Coador acts as a pre-built map of the project: compact, structured, local, and backed by source evidence.

The map has explicit limits:

• The default pass performs pattern matching rather than compilation. Missing heuristic evidence is not proof that a capability is absent.
• Convention plugins, generated build logic and dynamically created variants may require the optional Gradle pass.
• coador scan --gradle executes the target build's configuration and should be used only with a trusted project.
• Inventory completeness applies to the detector's documented source boundary, not to every value that could exist at runtime.
• The metadata freshness fast path cannot detect a content change whose path, size and modification time were deliberately preserved; use --force in that case.
• Coador complements symbol navigation, semantic search, build tools and device automation. It does not replace them.

Installation

Coador requires Python 3.11 or newer. Run version 0.1.0 without a permanent installation through uvx:

uvx --from coador==0.1.0 coador --version

To use the current checkout:

git clone https://github.com/automaticqa/coador.git
cd coador
uv sync --all-extras
uv run coador --version

An editable pip installation is also supported:

python -m pip install -e '.[dev]'

CLI

The CLI exposes six commands:

Run the basic workflow from an Android repository:

coador scan
coador overview
coador search "where do the base URLs come from"
coador show 03_architecture di_framework

Every command supports --json. Use --kb-dir to keep generated output outside the Android checkout. Use coador scan --force when source metadata cannot be trusted. For a trusted project with a JDK and Gradle wrapper, coador scan --gradle adds the configured Gradle model.

By default, generated knowledge lives here:

.coador/
  .refresh.lock
  manifest.json
  profile.json
  layers/

The scanner reads Android source and build configuration without changing them. It writes only to the selected knowledge-base directory and never edits the target repository's .gitignore. The selected destination is excluded from scanning and freshness fingerprints.

The .coador/ directory is designed to be committed when a team wants the project map reviewed and available without a local rescan. Hand-written Markdown above each layer's `` marker survives refreshes.

MCP

coador mcp (also available as coador-mcp) serves one repository over MCP stdio with six kb_* tools and matching kb:// resources. Register an explicit Android repository so the server cannot silently follow an unrelated working directory:

codex mcp add coador -- uvx --from coador==0.1.0 coador mcp \
  --repo "/absolute/path/to/your/android/project"
codex mcp list

Open Codex in the Android project, use /mcp to verify the server, and ask a project question. A useful first prompt is:

How should I add an instrumentation test to this project? Identify the runner, application, observed test tasks, dependency overrides, helper or robot to extend, and useful selectors. Cite the repository evidence for each answer.

Configuration can also use COADOR_REPO and COADOR_KB_DIR. See docs/mcp.md for trusted project-scoped configuration, paths with spaces, multiple repositories, Claude Code and other MCP clients.

Examples

Start with the local synthetic example to explore the current profile schema without a network or Android toolchain. For the pinned Now in Android walkthrough, generate the current CLI view outside the downloaded checkout:

git clone https://github.com/android/nowinandroid.git
git -C nowinandroid checkout 12f80da6518e161ed16a06a68e71fb8a873576d6
uvx --from coador==0.1.0 coador scan nowinandroid --kb-dir ../nowinandroid-coador
uvx --from coador==0.1.0 coador show 07_testing instrumentation_runner \
  nowinandroid --kb-dir ../nowinandroid-coador
uvx --from coador==0.1.0 coador show 07_testing test_tasks \
  nowinandroid --kb-dir ../nowinandroid-coador

The relevant output distinguishes evidence from limitations:

$ coador show 07_testing instrumentation_runner nowinandroid --kb-dir ../nowinandroid-coador
Instrumentation Runner (instrumentation_runner)
Detected: Observed: runner: androidx.test.runner.AndroidJUnitRunner, com.google.samples.apps.nowinandroid.core.testing.NiaTestRunner
source: heuristic

  app/build.gradle.kts:38  testInstrumentationRunner = "com.google.samples.apps.nowinandroid.core.testing.NiaTestRunner"

  limitation: Static scanning cannot resolve runner configuration supplied only by convention plugins or generated build logic

The evidence-first onboarding recipes add walkthroughs for CI instrumentation, launch targets and selectors, and Android Test Orchestrator isolation across three pinned public repositories.

Project status

Coador 0.1.0 is the first public release (2026-09-17). The package contains 84 detectors across nine layers, a local CLI, an MCP stdio server, optional Gradle probing, deterministic JSON/Markdown output, evidence provenance, inventory pagination, freshness checks and recovery from damaged generated output.

The configured CI matrix targets Linux on Python 3.11–3.13 and Windows/macOS on Python 3.12. Network and real-project Gradle checks remain opt-in.

For development:

uv sync --all-extras
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy
uv run python -m coador.registry --check
uv build

COADOR_INTEGRATION=1 uv run pytest -m slow additionally clones pinned public Android repositories; the Gradle case requires a suitable Android/JDK toolchain. Contributors can start with the starter contribution tasks. Optional public usage feedback follows the privacy boundaries in docs/adoption.md.

License

MIT. See LICENSE.