GigAI

GigAI is a local, user-controlled agent runtime. It keeps configuration, credentials, and work state under an operator-selected home directory, and makes every model call, review, and result inspectable rather than treating one model response as proof of correctness.

A Gig is a self-contained goal-graph package built on top of GigAI core. The boundary is fixed in one direction only — a Gig imports GigAI core; GigAI core never imports a Gig. Gigs are portable, reviewable units of work, not plugins the runtime depends on.

Scout, the first Gig

Scout ships with GigAI and implements find-jobs, a job-search workflow:

• Acquire — pull public postings from Exa search and the Greenhouse/Lever/Ashby applicant-tracking boards through an auto-managed watchlist.
• Assess — build a requirements-by-resume matrix for each posting, with suggestions and open questions. Defaults to a local model target; hosted targets are only used when explicitly configured.
• Present — a localhost API and a small web UI show acquired and assessed postings. Nothing leaves the machine, and no hosted model is called, without an explicit consent step in the UI first.

Everything Scout writes stays under your configured GigAI home and the bound project's workpad. Scout is one Gig among others GigAI can host; it gets no special runtime treatment.

Install

Requires Python 3.11+.

pip install gigai        # or: uv tool install gigai
gigai --version
gigai --help

Quickstart for humans

gigai setup        # interactive: workspace, access, models, roles
gigai doctor        # confirm the install is healthy
cd /path/to/a/git/repo
gigai init          # bind this repository as a GigAI project
gigai gigs          # list Gigs registered for this project

For agents

It's mostly agents — Claude, Codex, and similar — driving GigAI, so these commands are non-interactive and scriptable. Every one below was run against this build.

Setup

gigai setup --non-interactive \
  --home ~/.gigai --workpad-root ~/gigai-workpads --editor /usr/bin/true \
  --json

To add a hosted model target, include credential, endpoint, and model-target flags:

gigai setup --non-interactive \
  --home ~/.gigai --workpad-root ~/gigai-workpads --editor /usr/bin/true \
  --credential-ref provider=environment:MY_PROVIDER_TOKEN \
  --endpoint remote=openai_api:provider:https://api.example.com \
  --model-target remote=remote:some-model-name \
  --create-model-target remote \
  --json

--credential-ref records only an environment-variable name, never a secret value. Run gigai setup --help for the full reference, including Ollama loopback endpoints and per-target reasoning-effort options.

Bind a project

cd /path/to/target/repo
gigai init --username "agent" --json

--target accepts a path instead of the current directory. gigai init is idempotent for an already-bound project.

Scout: install and approve

Binding a project auto-materializes Scout as a candidate Gig — it is not pulled from gigai catalog (that command lists other built-in Gigs). Approving it follows the normal capability-review path: gigai capability review records reviewer judgment for the generated effect, then gigai approve <proposal-id> seals the version. Run gigai capability review --help / gigai approve --help for the exact required IDs, and gigai gigs --json to confirm Scout is active once approved.

Add a resume reference

gigai reference add --kind resume --file ./resume.pdf --json

--kind also accepts project_evidence, role_history, cover_letter.

The find-jobs.json config

Scout's find-jobs run reads an operator-authored config from <target_root>/find-jobs.json:

{
  "schema_version": "find-jobs-config:1",
  "roles": ["software engineer", "data engineer"],
  "merged_queries": ["software engineer OR data engineer"],
  "location": "Denver, CO",
  "remote": true,
  "published_after": "2026-09-15T00:00:00Z",
  "sources": { "exa": true, "ats": true, "hiringcafe": false },
  "default_assess_cap": 10,
  "default_model_target": "ollama_local"
}

default_model_target accepts ollama_local, codex_cli, or openrouter_api. hiringcafe is defined in the schema but not a live source in this release; leave it false.

Exa search

export EXA_API_KEY=...

Without it, Exa discovery refuses to run; ATS-board acquisition is unaffected.

Start the API

python -m gigai.scout.find_jobs.present_api --home ~/.gigai --target /path/to/target/repo

Loopback-only HTTP server (it refuses any non-loopback peer) that the Scout UI talks to.

The UI is not in the wheel

The Scout web UI is not bundled in the published package. It runs from a source checkout only:

git clone https://github.com/karthik446/gigai.git
cd gigai/src/gigai/scout/ui
yarn install
yarn dev

Point the dev server at the localhost API started above. PyPI gives you the CLI and API server, not a built UI.

Reading results and failures

• gigai run-details <run-id> --json reads durable Run state.
• gigai workpad path prints the canonical path of a registered Gig workpad, where journal, proposal, and Run state live.
• Any command that supports --json prints a structured result on stdout on both success and failure (see gigai doctor --json). A malformed invocation — a bad flag or missing argument — is a Click usage error and goes to stderr as plain text; check the exit code, don't assume JSON is always present.

Development

uv sync --locked --extra test
make test              # source + behavior + wheel-resource suites
make test-source       # source, unit, integration, and CLI tests only
uv run --locked pytest tests/behaviors/scout_find_jobs -q   # a focused slice

• src/gigai/ — core runtime: setup, config, journal, proposal/approval lifecycle, catalog, package boundary. Never imports a Gig.
• src/gigai/scout/ — the Scout Gig: find_jobs/ (acquire/assess/present), bundled goal-graph data, and ui/ (the separate Vite/React checkout above).
• .orchestrator/ — this project's coordination record: worker reports, decisions, and status. Committed, not a scratch directory.

Status

This is v0.1.8. Scout's find-jobs workflow is implemented and covered by the test suite above, including a deterministic end-to-end path from acquisition through the present API. It has not yet had a live-provider or human user-acceptance pass; treat what's proven by tests as proven, and everything else as unverified until it has been.

License

Apache-2.0. See LICENSE.