← Back to HumanLoopPUDU-AI DOCS

Pudu-AI, step by step.

Local-first hardware lab plus Agent Lab. Estimates never mix with measurements. Iteration 1 of Agent Lab is repo search only (rg + ast-grep). No LLM.

GitHub Interactive demo MCP catalog

What Pudu-AI is

Open-source terminal lab. Hardware side: detect the machine, list local models, grade compatibility, run llama-bench. Agent Lab side: deterministic code search so agents spend less context. Differentiator: OBSERVABILITY + CODE INTELLIGENCE + REPRODUCIBLE AGENT BENCHMARKING. Not a generic coding assistant.

→Estimated vs Measured are never mixed.
→Unavailable metrics are N/A — never invented.
→Apple unified memory is never called VRAM.
→Business logic does not depend on Ink.
→--lang is UI locale only, not ast-grep language.
→Network is optional (--no-network).

Clone and install

The npm name pudu is taken. This CLI is pudu-ai. Not published yet — install from GitHub. Node 20+.

git clone https://github.com/devjaime/pudu-ai.git
cd pudu-ai
npm install
npx . --lang es

Or: npm run pudu-ai -- --lang es. PUDU_AI_LANG=es or a Spanish LANG also select Spanish.

Inspect hardware

MVP is macOS Apple Silicon. Detects CPU, GPU, RAM / unified memory, runtimes. Hardware commands work without Python.

npx pudu-ai
npx pudu-ai hardware
npx pudu-ai doctor --lang es

Serial numbers and hardware UUID are stripped.

Discover local models

Ollama and llama.cpp GGUF paths. LM Studio GGUF in known dirs. MLX is detect-only for now.

npx pudu-ai models
npx pudu-ai models add-path ~/Models
npx pudu-ai setup
npx pudu-ai recommend

recommend --install --yes only pulls if the model fits this hardware. Never curl-pipes installers.

Benchmark with llama-bench

Measured values come from llama-bench and OS telemetry. Estimated values come from CanIRun.ai (midudev) or a local cache, always labelled Estimated.

npx pudu-ai benchmark
npx pudu-ai benchmark qwen3:8b --json --preset quick
npx pudu-ai history --csv
npx pudu-ai report --markdown

Presets: quick 512/128/3 · standard 2048/256/5 · stress 4096/512/10. GPU %, package power, temperature without extra permissions print N/A.

Install Agent Lab tools

Iteration 1 is pudu-ai repo search only. No LLM. python3 is required for search; rg and ast-grep are optional.

brew install ripgrep ast-grep
python3 --version

If rg or ast-grep is missing, JSON reports available: false. Hits are never invented. Hardware CLI still works without Python.

TEXT search with rg

Use when the bytes matter: identifiers, error strings, comments, YAML/JSON/TOML, filenames. Default for a plain identifier.

npx pudu-ai repo search validate_user
npx pudu-ai repo search validate_user --repo . --json
npx pudu-ai repo search validate_user --glob '*.py' --limit 20 --lang es

AST search is the wrong default here: comments and config files are not the language AST.

STRUCTURAL search with ast-grep

Use when the shape matters: definitions vs calls, decorators, imports. --structural or $FUNC / $$$ in the query.

npx pudu-ai repo search --structural 'def $FUNC($$$ARGS): $$$BODY' --repo .

validate_user as text hits comments and tests. def $FUNC hits definitions. Mixing them hides precision.

Hybrid and graph stubs

--intent UNKNOWN runs rg + ast-grep. RELATIONSHIP / IMPACT / SEMANTIC are stubs: empty matches, no invented edges, no LLM fallback.

npx pudu-ai repo search validate_user --intent UNKNOWN --json
npx pudu-ai repo search validate_user --intent TEXT --json

Intents: TEXT STRUCTURAL RELATIONSHIP IMPACT SEMANTIC UNKNOWN. --lang never sets ast-grep --lang.

Read JSON origins

TypeScript talks to python -m pudu_agent over stdin/stdout JSON. metrics.origin is MEASURED when tools ran. durationMs and matchCount are MEASURED.

npx pudu-ai repo search validate_user --json

Origins: MEASURED | ESTIMATED | DERIVED. Token counts without a real tokenizer stay ESTIMATED. Missing tools listed, never faked.

Wire MCP (optional)

Pudu MCP is local code intelligence. HumanLoop MCP is operators in Chile. Same protocol, different world.

{
  "mcpServers": {
    "pudu-ai": {
      "command": "python3",
      "args": ["-m", "pudu_agent"],
      "env": { "PYTHONPATH": "./python" }
    }
  }
}

Tools: pudu.ping, pudu.repo_search, pudu.repo_search_structural, pudu.classify_intent.

Flags (iteration 1)

--repo PATHRepository root (default: cwd)

--structural PATast-grep pattern (STRUCTURAL)

--intent INTENTOverride router

--glob GLOBRepeatable include glob

--limit NMax matches (default 100)

--jsonSearchResult JSON

--lang en|esUI locale only

--no-networkDisable outbound requests

Hardware CLI cheat sheet

npx pudu-ai hardware
npx pudu-ai models
npx pudu-ai recommend --link opencode --yes
npx pudu-ai tasks --for code,image,transcription --lang es
npx pudu-ai benchmark qwen3:8b --json --preset quick
npx pudu-ai compare
npx pudu-ai launch opencode
npx pudu-ai launch opencode --yes

Pudu-AI Score (hardware only)

Hardware performance only. Model intelligence is never folded in. If a dimension cannot be measured, its weight is redistributed. Pudu Task Score (Agent Lab) is a different metric and is not computed yet.

Speed35%generation tokens/s (measured)

Memory25%peak system memory / total RAM

Energy20%tokens/s/W when package power is measured

Thermals10%peak temperature / pressure when measured

Swap penalty10%peak swap used

Privacy

Benchmarks, model paths, and machine identifiers stay in ~/.pudu-ai/.
Nothing is uploaded. Agent Lab does not send repo contents to CanIRun or any catalog API.
Network is only the optional CanIRun catalog. --no-network disables outbound requests.
Future cloud providers must be explicit opt-in.

Not in iteration 1

repo scan / graph / explain / callers / path / impact
context build, mini-agents (scout → graph → context → builder → verifier)
task run, traces, experiment, Pudu Task Score / Effort
Agent Lab TUI

Later phases are specified so they are not invented ad hoc. Do not treat the homepage DEMO scores as live Task Score.

Measured: llama-bench + OS telemetry. Estimated catalog: CanIRun.ai by midudev. Pudu-AI does not copy CanIRun source.

npm test. Integration cases skip if python3, rg, or ast-grep is absent. Fixtures: tests/fixtures/repos/python-small.