Stratagent

A reviewable supply chain for agent skills.

Describe what you are building. Discover relevant skills and sub-agent definitions on GitHub, inspect their source and policy findings, and assemble approved configurations for Claude Code, Codex and portable Agent Skills environments.

Stratagent treats reusable agent instructions as software dependencies: pin the source, inspect the content, approve the exact plan, and record what was installed.

The CLI-first MVP combines transparent candidate ranking, commit-pinned snapshots, repository allowlists, content-bound approval and a provenance lockfile. A read-only MCP server exposes analysis, discovery and inspection to coding environments while keeping installation authority in the local CLI.

Python 3.11+. No third-party runtime dependencies, LLM API key or Git CLI required.

Why Stratagent

A reusable skill can carry instructions, references, scripts, permissions and license obligations. Installing it is a dependency decision. Stratagent makes that decision inspectable:

This is an early, working release. Planning is deterministic, static checks require human interpretation, and agent processes are not launched automatically.

Related MCP server: GitHub MCP

Quick start

Clone the repository and install locally:

git clone https://github.com/etrkk5/stratagent.git
cd stratagent
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/stratagent --help
.venv/bin/stratagent demo --workspace ./demo-workspace --apply
.venv/bin/stratagent verify --workspace ./demo-workspace

The offline demo uses original examples included in this project. Omit --apply to prepare review evidence and dry-run plans without activating platform files. Use a new directory for each demo. Its synthetic commits are explicitly labeled demo-offline in provenance.

Run directly from source without installing:

PYTHONPATH=src python3 -m stratagent plan "Build a Python API agent for data analysis"
PYTHONPATH=src python3 -m stratagent demo --workspace ./another-demo --apply

Discover, review, approve

mkdir my-agent
.venv/bin/stratagent init "Build a Python API agent with data analysis, tests and security review" \
  --workspace ./my-agent --platforms claude,codex,generic

.venv/bin/stratagent discover --workspace ./my-agent \
  --repo openai/skills \
  --repo VoltAgent/awesome-claude-code-subagents --limit 4

.venv/bin/stratagent recommend --workspace ./my-agent

Without --repo, discovery combines GitHub repository search with the seed catalogs openai/skills, anthropics/skills and VoltAgent/awesome-claude-code-subagents. Seeds are discovery sources, not trusted repositories. Search uses repository search followed by pinned Git tree/blob API calls; authenticated code search is not required. Results are bounded, not exhaustive.

Review a candidate using its id from the JSON output:

# Replace CANDIDATE_ID and APPROVAL_SHA256 with values from the output.
.venv/bin/stratagent inspect CANDIDATE_ID --content --workspace ./my-agent
.venv/bin/stratagent install CANDIDATE_ID --dry-run --workspace ./my-agent

# After reviewing all source files, licenses, findings and output paths:
.venv/bin/stratagent allow owner/repo --workspace ./my-agent
.venv/bin/stratagent install CANDIDATE_ID --apply \
  --approve APPROVAL_SHA256 --workspace ./my-agent

Use the candidate's actual repository name for allow. Installation requires the full approval SHA-256 from its dry-run, not the separate review_digest. Approval binds the absolute destination, source commit, source hashes, license, scanner version and generated file hashes. Changes invalidate the approval. Blocked candidates have no force-install option.

Generate task configurations after installing the resources you selected:

.venv/bin/stratagent configure --dry-run --workspace ./my-agent
# Use this configuration preview's own approval value:
.venv/bin/stratagent configure --apply --approve APPROVAL_SHA256 --workspace ./my-agent
.venv/bin/stratagent verify --workspace ./my-agent
.venv/bin/stratagent status --workspace ./my-agent

Configuration produces a five-role task graph covering architecture, implementation, testing, security review and integration. Only explicitly installed resources that pass verification are associated with tasks. Recommendations do not install or approve resources. Launching coding-agent processes is outside this MVP.

CLI reference

All results are JSON. --workspace works before or after the subcommand.

Exit codes: 0 success, 2 input/policy/access error, 3 verification drift, 4 discovery returned no candidates, 130 user interruption. Partial failures appear in errors; global rate/budget limits stop further requests and set stopped_early.

Workspace layout and portability

my-agent/
├── .stratagent/
│   ├── manifest.json          # Request, tasks, candidates, findings and scores
│   ├── policy.json            # Explicit local repository allowlist
│   ├── cache/<digest>.json    # Inert source text stored as JSON/base64
│   ├── lock.json              # Sources, hashes, licenses and approval records
│   ├── task-plan.json         # Task graph and approved resource assignments
│   ├── portable/skills/       # Generic Agent Skills output
│   └── notices/               # Notices for adapted definitions
├── .agents/skills/            # Codex skills and text references
└── .claude/
    ├── skills/               # Claude Code skills and text references
    └── agents/               # Read-only Claude Code sub-agent definitions

Skill adapters emit only name and description metadata and preserve relative text references and license/notice files. Original source content remains in the evidence cache. Claude sub-agents use Read, Grep, Glob and permissionMode: plan; the parent environment's permission settings also apply. Codex roles are represented as portable skills, not native multi-agent runtime configuration.

Stratagent does not change user-authored AGENTS.md, CLAUDE.md, .codex/config.toml, hooks or existing files. Conflicts stop installation. Upgrades and removal are not automated yet.

Security boundaries

• Read-only network access. Fixed-host HTTPS GET requests to GitHub's REST API, no redirects, request budgets and sanitized errors. Tokens are sent only in the API authorization header and never stored in manifests or lockfiles. TLS verification cannot be disabled; configure a trusted SSL_CERT_FILE if needed.

• No external execution. No Git clone, archive extraction, dependency installation, shell commands or plugin hooks run during discovery/installation. Installing Stratagent itself through pip is a separate package installation step.

• Content integrity. Sources are pinned to immutable commits. Git blob identities and file SHA-256 hashes are verified. Installation uses the reviewed snapshot, not a fresh download from a moving branch.

• Separate approval gates. The repository allowlist starts empty. Repository permission and exact plan-hash approval are both required. MCP cannot grant either permission.

• Bounded inspection. Limits are 256 KiB per file, 2 MiB/80 files per bundle, 8 MiB per HTTP response, 100 requests and 20 results per discovery. Truncated repository trees are refused.

• Conservative file policy. Symlinks, executables, submodules, traversal, absolute paths, control characters, non-portable paths and oversized/non-text content are refused. Installable bundles contain only .md, .txt, .rst and license/notice text. YAML, JSON, scripts and binaries block a bundle, including otherwise valid skills containing agents/openai.yaml.

• Static risk signals. Rules flag instruction overrides, remote shell execution, destructive commands, credential access and active permission/hook configuration. Security documentation can trigger false positives. These checks are not proof of safety; review every file before approval.

• Conservative license matching. Full supported license bodies are compared with pinned reference texts. Missing, unknown, customized or conflicting licenses are blocked. Supported texts are MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause and ISC. A match does not establish legal compatibility; review the actual notices and obligations.

• Controlled local writes. A directory lock serializes mutations. Ordinary failures roll back newly created files. Existing files are never overwritten; identical reinstallation verifies content before returning a no-op. There is no filesystem-wide power-loss transaction guarantee; run verify after interruption.

The local user and operating system are trusted. There is no signature/attestation protection against an attacker who can rewrite the manifest, cache and lockfile together, or OS sandbox protection against hostile concurrent replacement of parent directories. Activated skills remain subject to the coding environment's own security boundaries.

For GitHub rate limits, narrow discovery with --repo/--limit or set GITHUB_TOKEN with only the necessary read permissions. Stratagent does not read .env files.

Read-only MCP server

.venv/bin/stratagent serve --workspace /absolute/path/to/my-agent

The server uses newline-delimited JSON-RPC over stdio with MCP protocol version 2025-03-26. stdout contains protocol messages only. Tools are stratagent_analyze, stratagent_status, stratagent_inspect, stratagent_preview and stratagent_discover. MCP discovery reads from the network without saving files. The server is bound to one workspace, and tool arguments cannot redirect it elsewhere.

Adapt this example to your MCP client, replacing both paths:

{
  "mcpServers": {
    "stratagent": {
      "command": "/absolute/path/to/stratagent/.venv/bin/stratagent",
      "args": ["serve", "--workspace", "/absolute/path/to/my-agent"]
    }
  }
}

This is a generic example; Stratagent does not modify user settings. Automated tests and an installed-CLI subprocess exchange verify stdio behavior. MCP Inspector and actual Claude Code/Codex client interoperability have not been tested.

Development and verification

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m pip wheel . --no-deps --wheel-dir /tmp/stratagent-wheels

The 52 tests run without network access and cover pinned GitHub fixtures, integrity checks, malicious paths, symlink/executable handling, injection signals, license conflicts, approval scope, collisions, rollback, drift, task assignments, the CLI demo and MCP messages. Separate read-only live GitHub results are documented in validation.md.

See architecture.md for implementation boundaries and community-launch.md for a concise project description and launch copy.

Ecosystem references

Primary sources checked on October 18, 2026:

• Agent Skills specification

• OpenAI local skill locations

• Claude Code sub-agents

• GitHub tree API and blob API

• MCP stdio transport

• OpenAI skills, Anthropic skills and VoltAgent sub-agents

• SPDX license texts; pinned reference commits/hashes are in src/stratagent/data/license_sources.json.

Stratagent source code is MIT-licensed. Discovered resources retain their own licenses. Earlier prototype workspace state is not automatically migrated: create a new workspace rather than editing approval-bound files by hand.