Product and developer guide

From product context to evidence-backed action.

Before you start

CodeCaddie is for builders using AI who want to connect shipped behavior to product intent. Bring a local Git repository with at least one commit, a brief description of the product, and an installed Claude, Codex, or Grok CLI. Authorize the provider in its own terminal workflow first. CodeCaddie does not manage provider accounts or credentials; provider charges and policies may apply.

Download and install CodeCaddie for macOS or build the developer edition. Your first analysis duration depends on repository size and provider response time.

Create a workspace

Attach one local Git repository. CodeCaddie reads the current commit, records its immutable identity, and leaves the original checkout untouched. Uncommitted and untracked changes are outside that snapshot. Commit work you want assessed before starting another analysis.

Add product context

Describe the product, customers, desired outcomes, strategic priorities, and risks. The optional website remains reference metadata and is not fetched.

You can also select up to 10 PDF, PowerPoint, Word, text, or Markdown files. Each file must be a supported regular file no larger than 25 MiB; the combined selection is limited to 100 MiB and 100,000 extracted characters. Selecting a file authorizes its bounded extracted text to be sent to the chosen AI provider when goals are generated. Extracted text is never stored.

Generate and approve goals

Choose an already-installed Claude, Codex, or Grok CLI. CodeCaddie first builds a source-grounded product profile, then asks for six to nine editable goals. Every generated set must include durable business outcomes and explicit architecture, observability, testing, security, recovery, and release-safety coverage. Product signals add applicable goals such as tenant isolation, integration contracts, webhook reliability, AI controls, or scale safeguards.

Provider output is validated before it can replace the current set. Invalid, generic, or drafting-placeholder output fails visibly after bounded retries; approved goals stay intact.

Analyze the repository

CodeCaddie creates a disposable, history-free snapshot of the approved commit and gives the selected provider bounded read-only tools. Provider activity shows the current phase and sanitized repository-relative file progress. It never includes source text, prompts, attached-document text, search terms, or absolute device paths.

The saved report classifies support for every goal, binds claims to path, line, and hash coordinates from the scanned commit, explains architecture findings, and ranks recommended actions. Download Word report exports the current report to the Downloads folder.

Read the report, then take one action

Start with a recommended action and its business impact. Inspect the linked evidence from the scanned commit, then give your coding agent a focused implementation or investigation task. Review and test the change, commit it, and analyze again against the approved goals. See the worked document-search example.

Found

The cited evidence supports the check.

Partly found

The evidence supports part of the check.

Evidence shows a gap

The assessment cites evidence contrary to the check. Inspect that evidence before deciding what to change.

Could not find evidence

The analysis did not establish the check. Missing evidence is not automatically a confirmed defect.

Could not verify

The analysis could not establish an answer. This can include unavailable or invalid evidence, unanswered batches or an incomplete analysis, and checks that code alone cannot answer. Read the rationale.

Weighted support measures support among assessed checks. Within each goal, supported checks count as 1, partial checks as 0.5, and unsupported checks as 0. Goal scores are weighted by goal priority. Unverified checks are excluded and shown separately; read their count alongside the score. If no checks can be assessed, there is no score. This is not test coverage, a percentage of finished features, or proof of a business outcome. Read an “Incomplete” overall assessment alongside its individual checks.

History becomes useful after multiple analyses. Compare both the goal set and commit before interpreting a change in weighted support.

Local storage and recovery

Workspace state and signed event history are authenticated and encrypted in one per-platform data directory. Some device-local configuration and references remain outside encrypted workspace payloads. Repository source and extracted attachment text are excluded from stored state, reports, IPC, logs, recovery exports, and provider diagnostics.

Build the developer edition

Contributors need Git, Node.js 24, pnpm 11.22.0, Rust 1.95.0 (pinned by the repository), and an installed supported provider for live analyses. Native SDK 0.10.1 downloads its pinned Zig toolchain on first use.

git clone https://github.com/tailored-ai-solutions/codecaddie.git
cd codecaddie
pnpm install --frozen-lockfile
cargo build --workspace --locked
pnpm dev:isolated

Use isolated developer data

This command creates an owner-only data directory outside the checkout. Use it for testing instead of the real app data directory.

pnpm dev:isolated

Install or remove the developer app

pnpm install:local
pnpm install:local -- --no-launch
pnpm install:local -- --uninstall

The side-by-side developer identity never replaces the stable application and leaves its own data in place when uninstalled.

Run the complete gate

pnpm check
pnpm build