Factory documentation / Install

Install

Pick a local session, a deterministic hook, or a pinned CI workflow. Keep authentication and target policy explicit.

Before you begin

Python 3.9+ and Git.
At least one installed, authenticated AI CLI: pi, claude or antigravity. Engine availability and containment rules vary; check boundaries.
bd is optional for a configured Beads sink; gh is optional for GitHub issue input and promotion.

Local installation

git clone https://github.com/PaulKinlan/agents.git
cd agents
./install.sh
./factory list
./factory --agent

No --version flag is provided. Use ./factory --help to inspect installed commands.

Models & authentication

Local runs reuse your authenticated CLI session. For headless action runs, supply the provider key as a GitHub Actions secret via model_api_key (Gemini or Anthropic); DeepSeek uses deepseek_api_key. Provider environment variables include GEMINI_API_KEY, ANTHROPIC_API_KEY and DEEPSEEK_API_KEY. Never store keys in a workflow file or the site.

Choose a boundary you can verify.

On Linux, pi requires a working bubblewrap sandbox unless an explicitly trusted private target opts into the exceptional unsandboxed path. Do not treat an agent prompt as confinement.

GitHub Actions composite action

Pin both the action and fetched factory payload to reviewed 40-character commits. Give the job only the permissions it needs. The full workflow and its current pin belong in INTEGRATION.md.

# In your workflow, after actions/checkout:
- uses: paulkinlan/agents/.github/actions/factory@57d2a2951567973da7637b9016c0c5e67ad7a73d
  with:
    agent: secret-scan
    target: '.'
    sink: file
    factory_ref: 57d2a2951567973da7637b9016c0c5e67ad7a73d
    model_api_key: ${{ secrets.GEMINI_API_KEY }}

Set permissions: contents: read by default. Use a write permission only for an approved workflow that requires it. The action uploads a full report as an authenticated artifact and uses a reduced step summary; do not copy raw report content into a public page.

Hooks, schedules & skills

Pre-commit

Install the fast deterministic hook. Blocking hooks do not invoke models.

./factory hook install --target .

Interactive skills

Link the factory skills into supported local CLI skill directories.

./factory skills install

Recurring runs

Inspect registered schedules before installing any.

./factory schedule list