frontier-scout 0.4.1

A local AI adoption radar for tools, MCP servers, agent frameworks, and model drops.

Frontier Scout

Local-first try-before-trust for AI tools, agents, MCP servers, models, and risky engineering changes.

Quickstart  ·  Demo  ·  Roadmap  ·  Bug report  ·  Feature request  ·  Releases

📑 Table of contents

• About the project
• Built with
• Quickstart
• 60-second demo
• Usage — killer workflow
• Safety model
• Cost
• Roadmap
• Contributing
• License
• Acknowledgments

---

🔭 About the project

Frontier Scout answers the question technical teams now hit every week:

Should this AI tool, agent, MCP server, model, or engineering change get any access to our code, shell, browser, network, or credentials?

Three compatible surfaces ship in one CLI:

• Tool Test Lab / Adoption Firewall — one-link evaluate, trial, and guard workflows that record permission manifests and try-before-trust receipts before a tool touches a real project.
• AI Tool Radar — a local adoption radar that turns public AI-tool signals into ADOPT / TRIAL / ASSESS / HOLD verdicts with source evidence.
• Incident Change Scout — a graph-aware engineering workflow that turns an incident ticket into cited context, a bounded remediation plan, approval interrupts, trace/audit logs, and an eval result.

The posture is deliberately boring in the good way: CLI first, SQLite/local files by default, static reports, no hosted telemetry, no hidden auto-installs, and explicit approval before risky actions.

Why not just use newsletters or GitHub Trending?

Option	What it gives you	What is missing
Newsletters	Good awareness	Not repo-aware, not source-verifiable, rarely actionable.
GitHub Trending	Popularity signal	No risk/fit/adoption-cost judgment.
Manual research	Highest nuance	Slow, inconsistent, easy to skip when busy.
Frontier Scout	Source-backed verdicts and lab next steps	Requires your API key for live scans.

---

🧰 Built with

---

⚡ Quickstart

Prerequisites: Python 3.11+ and git.

git clone https://github.com/ajaysurya1221/frontier-scout
cd frontier-scout
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
frontier-scout --help

For a guided first run, open Mission Control:

frontier-scout setup --repo .

Mission Control checks your repo fingerprint, the import-evidence scanner finds the third-party libraries you actually use, and provider availability shows up as cards — all without reading secrets, logging into services, installing tools, or sending repo content to an LLM. Limited terminals can use frontier-scout setup --plain; automation can use frontier-scout setup --json.

After PyPI publish the install collapses to:

pipx install frontier-scout
uvx frontier-scout demo

---

⏱ 60-second demo

No API key. No Slack workspace. No cloud setup.

make demo
open .scratch/incident-demo/answer.md

The incident demo writes:

• .scratch/incident-demo/answer.md — cited remediation answer.
• .scratch/incident-demo/trace.jsonl — local OpenTelemetry-shaped spans.
• .scratch/incident-demo/audit.jsonl — Cloudflare-style audit records.
• .scratch/incident-demo/eval.json — golden eval score.

Then run the AI tool radar demo:

frontier-scout demo
open demo/briefing.html

The radar demo writes demo/briefing.html, demo/briefing.md, demo/verdicts.json, demo/cost-breakdown.md, and demo/judge-trace.md.

---

🛰 Usage — killer workflow

Someone drops a GitHub repo, MCP server, plugin, model, or agent framework in a newsletter or team chat. Frontier Scout turns that link into a local adoption decision instead of a vibes-based "looks safe" answer:

frontier-scout init --repo .
frontier-scout evaluate <tool-url>
frontier-scout trial <tool-or-url> --dry-run
frontier-scout guard --repo .
frontier-scout report

• init writes a local stack profile under ~/.frontier-scout (languages, package managers, container files, agent configs, and v0.4 import evidence from a tree-sitter pass).
• evaluate records source-backed local evidence and a permission manifest for one URL — capability map included.
• trial --dry-run writes an adoption receipt without installing anything; full trials use the hermetic lab.
• guard checks the local evidence ledger for risky tools that still need a stored trial receipt; CI-friendly exit codes.
• report renders the static HTML executive radar.

Inspect living packs and repo-relevant dependency upgrades:

frontier-scout packs list
frontier-scout packs show mcp
frontier-scout profile --repo . --dependencies
frontier-scout deps scan --repo .

---

🔒 Safety model

Frontier Scout handles untrusted public content and can optionally execute untrusted packages in the lab, so the safety rails are load-bearing:

• Source text is treated as untrusted data, not instructions.
• Tool names are checked against the source pool to reduce hallucinated verdicts.
• Source URLs must pass a domain allowlist.
• Incident and breach headlines are blocked from becoming tool recommendations.
• ADOPT requires enough readiness evidence or gets demoted.
• Adoption Firewall fails closed on unknown MCP/tool capability surfaces.
• guard never modifies the repo; it only reads local evidence and policy.
• Lab subprocesses receive a stripped environment, wall-clock timeout, size caps, and generated-script secret scanning.
• The import-evidence scanner is deterministic, local, and offline. It parses ASTs via tree-sitter, never sends source content to an LLM, and never reaches the network.

See SECURITY.md for the threat model.

---

💸 Cost

The offline demo is free. A normal live weekly scan is designed to stay cheap:

Component	Typical cost
Sonnet score pass	~$0.15
Sonnet verdict pass	~$0.04
Optional Opus judge	~$0.12
Weekly scan	~$0.30

Set JUDGE_ENABLED=false to skip the Opus judge when you want the cheapest possible run.

---

🗺 Roadmap

• v0.1 — CLI scaffold, local demo, SQLite store, public docs.
• v0.2 — Living Scout Packs, dependency intelligence, Adoption Firewall (evaluate/trial/guard/policy), Incident Change Scout.
• v0.3 — Mission Control terminal setup, provider detection, Scout Pack multi-select, plain/JSON outputs.
• v0.4.0 — Monorepo profile walker + tree-sitter import-evidence scanner (Python and JS/TS), repo-relative manifest_path, --no-imports fast path, .understand-anything/ detection.
• v0.4.1 — Mission Control v2 redesign: branded splash, designer palette, focus borders, modal quit/help/repo-path, RichLog result, sticky status banner, README v2.
• v0.5 — Repo-signal cache, tree-sitter Go/Rust/Ruby support, first-party module filtering.
• v0.6 — MCP/plugin surface, stronger sandbox backends, optional output integrations on top of the same local evidence store.

See ROADMAP.md for the longer view.

---

🤝 Contributing

The fastest useful PRs improve the CLI/report path, validator coverage, source quality, or lab isolation.

• Read CONTRIBUTING.md.
• Browse good first issues.
• Respect the Code of Conduct.

Development loop:

make setup
make demo
make test
make eval
make audit
python -m compileall scripts outputs tests frontier_scout
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q

CI runs compile checks, non-live tests, and a tracked-file secret scan.

Releasing a tagged version

1. Bump project.version in pyproject.toml and frontier_scout/__init__.py.
2. Append a matching ## X.Y.Z - YYYY-MM-DD section to CHANGELOG.md.
3. Merge to main.
4. Push annotated tag vX.Y.Z.

Tag pushes trigger .github/workflows/release.yml, which builds distributions, creates a GitHub Release from the matching changelog section, and (via manual workflow_dispatch) publishes to PyPI via trusted publishing.

---

📄 License

Distributed under the MIT License.

---

🙏 Acknowledgments

• Textual — the framework that makes the Mission Control TUI possible.
• tree-sitter-language-pack — precompiled grammars for the v0.4 import-evidence scanner.
• Pydantic — typed models throughout.
• othneildrew/Best-README-Template — the structure this README borrows from.
• Lum1104/Understand-Anything — the tree-sitter half of its design pushed us to ship deterministic import evidence instead of substring heuristics.

↑ back to top