Replicant

Replicant

Use durable, human-findable local clones of external repositories as source context. Prefer real source code over stale docs, generated summaries, or web snippets.

Replicant is a clone shelf, not a hidden cache, generated-docs system, or custom CLI.

<!-- REPLICANT_CONFIG configured: false clone_root: ~/clones default_update_policy: auto-clean-only default_clone_depth: full preferred_transport: ssh inventory_file: ~/clones/README.md last_setup_at: REPLICANT_CONFIG -->

Clone layout

<clone_root>/<host>/<owner>/<repo>

The clone_root in the config block above is authoritative.

Order of operations

1. Read config from the REPLICANT_CONFIG block above. 2. Extract repo clues: explicit URL, owner/repo, package name, keywords. 3. Normalize inputs — strip URL suffixes to host/owner/repo. 4. Search locally before any web search: check inventory file, then clone directories. Exact owner/repo beats substring. 5. If one confident local match, use it. If multiple, disambiguate locally; ask the user only if still ambiguous. 6. If no local match, resolve via web/code search, then map to clone_root/<host>/<owner>/<repo>. 7. Clone if missing (configured transport/depth). Ask before full-cloning obviously large repos. 8. If clone exists, update per configured policy. See setup for policy definitions. 9. Record git rev-parse HEAD and git status --porcelain before use. 10. Search and read source directly. 11. Answer with evidence: commit SHA, file paths, line ranges.

Research rules

• Treat external clones as read-only by default.
• Do not commit, push, branch, reset, git clean, or delete clone contents unless explicitly asked.
• Preserve local modifications; do not auto-update dirty clones.
• Do not install dependencies or run builds/tests unless necessary for the answer.
• Prefer implementation evidence over README claims.
• Cite commit SHA and file paths with line ranges when practical.

First-run setup

If configured: false in the config block above, run setup before first use.

First-run setup must be intentional, not silent. Walk the user through every configurable choice in the setup reference before writing config. You may recommend defaults and the user may accept all of them, but do not assume defaults without an explicit user choice or confirmation.

References

• Workflow recipes — clone, update, search, resolution, and answer commands.
• Setup reference — first-run prompts, policy definitions, config format, fallback paths.

Replicant setup

Replicant has no CLI and no hidden map. First-run state lives in the skill's REPLICANT_CONFIG block when possible.

First-run prompt

First-run setup is an intentional configuration flow. Do not silently assume defaults. The user may accept the recommended defaults, including accepting all recommendations at once, but only after the agent has presented each configurable choice and the user has explicitly confirmed their selections.

Use this concise setup prompt:

Replicant keeps durable source clones for humans and agents. I can recommend defaults, but I will not assume them without your confirmation.

Please choose each setup option, or say "accept recommendations" to use all recommended values:

1. Clone root
   - Recommended: ~/clones
   - Why: human-findable, central, outside project repos
   - You can choose any directory.

2. Update policy for existing clones
   - Recommended: ask
   - Options:
     - ask: ask before pulling existing clones
     - auto-clean-only: auto-pull only when the working tree is clean
     - never: never update unless explicitly asked

3. Clone depth
   - Recommended: 1 (shallow)
   - Options:
     - 1: shallow clone, fast and small
     - full: full history for archaeology, blame, and tag-heavy work

4. Preferred transport
   - Recommended: https
   - Options:
     - https: simplest for public repos
     - ssh: useful for private repos and configured SSH keys

5. Inventory file
   - Recommended: <clone root>/README.md
   - Purpose: human-readable list and notes for useful clones

Reply with your choices, or say "accept recommendations".

Configuration choices:

• clone_root
• recommended: ~/clones
• should be human-findable and outside project repos
• default_update_policy
• recommended: ask
• ask: ask before pulling existing clones
• auto-clean-only: auto-pull only when working tree is clean
• never: do not update unless user explicitly asks
• default_clone_depth
• recommended: 1
• 1: shallow clone, fast and small
• full: full history, useful for archaeology/blame/tag-heavy work
• preferred_transport
• recommended: https
• https: simplest for public repos
• ssh: useful for private repos and configured SSH keys
• inventory_file
• recommended: <clone_root>/README.md
• should live with the clone shelf unless the user chooses otherwise

Setup commands

For default setup:

mkdir -p "$HOME/clones"
test -f "$HOME/clones/README.md" || cat > "$HOME/clones/README.md" <<'EOF'
# Local Source Clones

This directory contains durable external source clones for humans and coding agents.

Default layout:

~/clones/<host>/<owner>/<repo>

Examples:

~/clones/github.com/facebook/react ~/clones/github.com/tanstack/router

## Policy

- Clones are source context, not working copies.
- Agents should treat them as read-only unless explicitly told otherwise.
- Agents may clone missing repositories here.
- Agents should ask before updating existing clones unless configured otherwise.
- Agents should not hide external clones inside project directories.

## Inventory

Add useful repos below.
EOF

Edit skill config

After setup, edit SKILL.md:

<!-- REPLICANT_CONFIG
configured: true
clone_root: ~/clones
default_update_policy: ask
default_clone_depth: 1
preferred_transport: https
inventory_file: ~/clones/README.md
last_setup_at: YYYY-MM-DD
REPLICANT_CONFIG -->

Use the current date for last_setup_at.

Fallback config

If the skill cannot be edited, create ~/clones/REPLICANT.md:

# Replicant Config

configured: true
clone_root: ~/clones
default_update_policy: ask
default_clone_depth: 1
preferred_transport: https
inventory_file: ~/clones/README.md
last_setup_at: YYYY-MM-DD

On future uses, read this file after the skill config block.

Replicant workflows

Variables

For a GitHub repo:

CLONE_ROOT="$HOME/clones"
HOST="github.com"
OWNER="owner"
REPO="repo"
LOCAL="$CLONE_ROOT/$HOST/$OWNER/$REPO"

Expand ~ manually in shell commands; do not quote paths containing literal ~ expecting shell expansion inside variables.

Normalize repository inputs

Accept any of these formats:

owner/repo
https://github.com/owner/repo
https://github.com/owner/repo/tree/main/path
https://github.com/owner/repo/blob/main/file.ts
git@github.com:owner/repo.git

Strip URL suffixes (/tree/..., /blob/..., /issues/..., /pull/...) and normalize to host/owner/repo. Then map to $CLONE_ROOT/$HOST/$OWNER/$REPO.

Local-first repo resolution

For ambiguous names (e.g. "mole", "react router", "the auth library"), search the local shelf before web search:

KEYWORD="mole"

# Inventory first, if present.
test -f "$CLONE_ROOT/README.md" && rg -i -- "$KEYWORD" "$CLONE_ROOT/README.md"

# Then human-findable clone paths.
find "$CLONE_ROOT" -mindepth 3 -maxdepth 3 -type d \
  | grep -i -- "$KEYWORD"

# Confirm candidate repos.
test -d "$CLONE_ROOT/github.com/owner/repo/.git" \
  && git -C "$CLONE_ROOT/github.com/owner/repo" rev-parse HEAD \
  && git -C "$CLONE_ROOT/github.com/owner/repo" status --porcelain

Selection rules:

• Exact repo name match beats substring match.
• Exact owner/repo match beats repo-only match.
• A locally cloned repo beats a web result unless evidence shows it is the wrong project.
• If two local clones are equally plausible, ask the user to choose.
• If local search finds no plausible clone, use web/code search to identify the canonical repo.

Check for an existing clone

test -d "$LOCAL/.git" && echo exists || echo missing

If it exists, inspect before updating:

git -C "$LOCAL" status --short
git -C "$LOCAL" branch --show-current
git -C "$LOCAL" remote -v
git -C "$LOCAL" log -1 --oneline

Clone missing repo

HTTPS shallow clone:

mkdir -p "$(dirname "$LOCAL")"
git clone --depth 1 "https://github.com/$OWNER/$REPO.git" "$LOCAL"

SSH shallow clone:

mkdir -p "$(dirname "$LOCAL")"
git clone --depth 1 "git@github.com:$OWNER/$REPO.git" "$LOCAL"

Full clone: omit --depth 1.

Update existing clone

If working tree is dirty, do not pull automatically. Report dirty files and ask.

If clean and policy allows update:

git -C "$LOCAL" pull --ff-only

For shallow clone refresh:

git -C "$LOCAL" fetch --depth 1 origin
git -C "$LOCAL" pull --ff-only

Never run without explicit user approval:

git -C "$LOCAL" reset --hard
git -C "$LOCAL" clean -fd
rm -rf "$LOCAL"

Inspect source

Start broad:

ls "$LOCAL"
find "$LOCAL" -maxdepth 2 -type f \
  \( -name "README*" -o -name "package.json" -o -name "Cargo.toml" -o -name "go.mod" -o -name "pyproject.toml" \)

Search before reading:

rg "<term>" "$LOCAL"
find "$LOCAL" -type d \( -name test -o -name tests -o -name examples -o -name docs \) | head

Prefer this reading order:

1. README/docs for public concepts. 2. Manifests for entry points and exports. 3. Source files for actual behavior. 4. Tests/examples for usage. 5. Issues/PRs only when history or rationale matters.

Package name without repo

If the user names a package but not a repo:

1. Check project manifest metadata if relevant. 2. Try package metadata:

   npm view <package> repository.url
   npm view <package> homepage

3. Search GitHub if needed:

   gh search repos "<package>" --limit 5

4. Ask the user when ambiguous.

Do not invent repo mappings.

Version-specific questions

If user asks about a tag/version:

git -C "$LOCAL" fetch --tags
git -C "$LOCAL" tag | rg "<version>"
git -C "$LOCAL" checkout "<tag>"

Tell the user if you checked out a tag or detached HEAD. Restore the previous branch afterward when practical, or report the final checkout state.

Answer format

Include:

• local path used
• commit SHA
• files/symbols inspected
• concise explanation grounded in source

Commit commands:

git -C "$LOCAL" rev-parse --short HEAD
git -C "$LOCAL" log -1 --oneline

Example phrasing:

Based on `~/clones/github.com/tanstack/router` at commit `abc1234`:

- `packages/router-core/src/router.ts` defines ...
- `packages/router-core/tests/navigation.test.ts` shows ...