Agent-Pantograph Template

Between world and workshop, there is a watched gate.

What is Agent-Pantograph?

Agent-Pantograph is a lightweight, safety-focused AI terminal harness for local agent-like workflows.

Keep routine processing local. Send the model evidence, not noise.

It stands on four pillars:

1. Reduce token waste — routine processing stays local; the AI receives compact evidence packets, not raw terminal output.
2. Reduce shell risk — bounded, reviewed routines behind a watched gate; no arbitrary command execution.
3. Make smaller models more useful — structured summaries are inputs small/local models handle reliably; raw logs are not.
4. Keep the human in authority — the human approves every run; the harness gates, the human decides.

The mechanism: Ag-lets process local noise into compact reports and structured summaries; the workflow validates and records; the AI interprets shaped evidence; the human decides.

It helps you get more from lower-cost settings and smaller models by turning risky free-form terminal work into bounded, inspectable local routines.

It uses:

• bounded scripts;
• human approval gates;
• compact reports;
• deterministic routines;
• repo-backed documentation;
• clear safety and privacy boundaries.

These all stack together to reduce shell risk, token load, drift, and hallucinated local actions while keeping the human in control.

The basic pattern is deliberately simple:

AI proposes.
Human approves.
A bounded local routine runs.
A compact report returns.
AI interprets.
Human decides the next gate.

Agent-Pantograph is not a magic autonomous agent. It is a harness for making AI-assisted terminal work safer, clearer, cheaper, and easier to repeat.

Why this exists

Modern AI agents are powerful, but local terminal access can get messy fast.

A model may:

• invent shell commands;
• forget constraints;
• request too much context;
• read or output too much data;
• drift away from the task;
• hallucinate paths, tools, or results;
• turn a narrow job into a sprawling terminal adventure.

Agent-Pantograph pushes against that pattern by moving repeatable local work into small deterministic routines.

Instead of asking an AI model to improvise terminal commands every time, you give it a safer workflow:

Define the task.
Choose or create a bounded script.
Review the scope.
Run only after human approval.
Return a compact report.
Let the AI interpret the result.

This lets the AI do what it is good at: planning, reviewing, summarising, comparing, and explaining.

The deterministic routine does what it is good at: running the same narrow local procedure the same way every time.

What this template provides

This repository is a starting scaffold for building Agent-Pantograph-style workflows.

Repository layout

This is a template scaffold: some folders carry active v0.1 content, while others are template contract folders — deliberate destinations that a cloned user workspace is expected to fill over time. An empty contract folder is part of the intended layout, not a missing feature. v0.1 ships docs, a starter Ag-let library (one example plus three read-only review Ag-lets), illustrative examples, the v0.1 assisted runner under runner/, and labelled reserved surfaces.

Active in v0.1:

Area	Purpose
aglets/	Starter Ag-let library (one example Ag-let, three read-only review Ag-lets, plus three Ag-let templates)
aglets/schemas/	Ag-let manifest JSON Schema (validation)
runner/	v0.1 assisted runner — human-invoked; executes gated, pinned Ag-lets after explicit approval
docs/	Architecture notes and workflow documentation
examples/	Fictional request/report pair showing the safe workflow shape
governance/	Release, privacy, safety, and review gates
assets/	Project identity assets

Template contract / reserved surfaces (labelled, not yet active):

Area	Intended role
control/	Reserved policy/control destination (holds a draft request template)
schemas/	Reserved global schema surface (active schemas live in aglets/schemas/)
scripts/	Reserved surface for template-safe helper scripts (none approved yet)
templates/	AI-packet templates (templates/user_repo/, active) + reserved general template space

The reserved folders are not evidence that a control system or script library is implemented. Each contains its own README stating its status.

Inside this repo, bounded scripts may be called Ag-lets. The term simply means a small, inspectable task capsule with a clear purpose, declared scope, and known report format.

Core workflow

A healthy Agent-Pantograph workflow should look something like this:

1. Human asks for help.
2. AI proposes a bounded local task.
3. Human reviews the proposed action.
4. A script runs locally with limited scope.
5. The script returns a compact report.
6. AI explains the report.
7. Human decides whether to stop, continue, or approve another step.

The machine remains under human control.

The AI does not get silent authority over the terminal.

Safety model

By default, Agent-Pantograph assumes:

no arbitrary command execution
no sudo by default
no package installs by default
no driver changes by default
no service changes by default
no deletion by default
no credential inspection
no private key inspection
no hidden background agent
no silent persistence
mitigated safety, by design

Higher-risk operations should be separated into explicit, reviewable, risk-tiered procedures.

The goal is not to claim perfect safety. The goal is to narrow the dangerous parts of local AI-assisted work, make them inspectable, and keep the human in the approval loop.

Why bounded scripts help

Free-form terminal work makes the model carry too much weight.

Bounded deterministic routines can reduce that burden.

They can:

• perform repeatable scans without dumping huge outputs into chat;
• enforce known paths and exclusions;
• return compact reports instead of raw terminal noise;
• keep smaller models on a tighter rail;
• reduce token load by summarising locally;
• reduce hallucinated local actions by using known procedures;
• make successful workflows reusable.

This is especially useful when working with smaller models, lower-cost settings, local models, or long-running projects where context can get expensive.

Example use case

A casual request might be:

Check this repo for old project names before I publish it.

Without a harness, an AI might suggest a messy chain of shell commands and then ask you to paste back a wall of output.

With Agent-Pantograph, the task can become a bounded routine:

Task: fossil-name scan
Risk: read-only
Allowed path: this repository
Forbidden: secrets, home directory scans, deletion, writes
Output: compact JSON or Markdown report
Human approval: required before running

The AI can then interpret the compact report and suggest the next human-approved gate.

Public/private split

Agent-Pantograph is designed to keep reusable template material separate from private runtime state.

A public template may contain:

docs
schemas
examples
bounded script patterns
fake reports
runner contracts
safety guidance
privacy guidance
release checklists

A private runtime area may contain:

local configuration
real reports
machine-specific notes
operator decisions
project traces
task results

Private runtime state should not be copied into a public template without review and sanitisation.

What this is not

Agent-Pantograph is not:

• a fully autonomous OS agent;
• a hidden daemon;
• a remote-control shell for an AI model;
• an absolute guarantee of safety;
• a replacement for human judgement;
• a production-ready automation platform.

It is a lightweight harness for safer, more repeatable AI-assisted terminal workflows.

A v0.1 assisted runner now exists under runner/ and can execute eligible Ag-lets through a human-approved, pinned path (see runner/README.md for the full contract). It remains scaffold-adjacent: manual mode (Mode A) is always available and required for anything the runner doesn't yet cover.

Not included yet

This template is a scaffold. To set expectations honestly, the following are not part of this version:

• No write-tier execution, Mode C watched-drop, or external transports are included — see runner/README.md for exactly what the v0.1 runner does and does not do.
• No background daemon is included.
• No hidden persistence is included.
• No prompt-pack or setup-GPT scaffolding is included.
• No external integrations are included.
• No delete or move workflows are included in the default mode.
• The example Ag-let (duplicate_file_scout) and the three read-only review Ag-lets (script_summariser, script_safety_scan, manifest_code_consistency_check) are all still marked REVIEW_REQUIRED.

The public-bound release tree is produced from this content as a single clean-export commit; the release gates in governance/PUBLIC_RELEASE_CHECKLIST.md are applied before any visibility flip.

Current status

Status: v0.1 assisted-runner core complete
Template mode: enabled (GitHub template setting)
Visibility: GitHub repository settings are authoritative for current visibility
Release procedure: visibility changes require explicit maintainer HITL approval and
are never automatic; if you are viewing this repository publicly, that approval has
already been given
Public-bound tree: ships as a single clean-export commit under a neutral git identity;
private vulnerability reporting is enabled immediately after any public visibility flip

The public-bound release tree passes a public-readiness scan (no secrets, personal data, private paths, or naming/safety-overclaim residue) before any flip. Development and pre-template working history are retained separately in private repositories.

The scan covers:

• secrets;
• tokens;
• personal data;
• private paths;
• raw logs;
• runtime reports;
• machine-specific assumptions;
• outdated project names;
• overclaims about autonomy or safety.

See:

governance/PUBLIC_RELEASE_CHECKLIST.md
SECURITY.md
PRIVACY.md
AGENT_PACKET.md

Design principles

Files hold memory.
Commits hold history.
Reports carry evidence.
Scripts bound action.
Schemas give discipline.
The AI interprets.
The human approves.
The machine stays yours.
Safety and risk-mitigation built in.

Suggested next gates

When adapting this template for your own use:

1. Review all bounded scripts and mark their status accurately.
2. Validate schema and registry expectations.
3. Review docs for clarity and overclaims.
4. Keep private runtime state (reports, logs, machine notes) in a private repo or local folder, never in a public copy.
5. Confirm no logs, secrets, tokens, local paths, or personal data are present before publishing anything derived from this template.

License

Licensed under the Apache License, Version 2.0. See LICENSE.