Workweaver

Workweaver is an AI business operating system built around one codebase and multiple deployment profiles:

• managed_saas for managed cloud runtime
• self_host_production for customer-managed deployments
• standalone and local-first development paths

First-run wizard (recommended)

After pip install workweaver (or cloning the repo), run the wizard:

ww welcome

The wizard asks how you intend to use Workweaver and routes you to the canonical setup for that path:

1. Sign up for managed SaaS — opens https://workweaver.ai/signup in your browser. After signing up, run ww auth login to connect this CLI.
2. Self-host on AWS — generates infra/terraform/dev/terraform.tfvars and previews terraform plan. Never runs terraform apply for you; review the plan and apply manually when you are ready.
3. Self-host locally — runs ww init --self-host (Docker stack, vendored dashboard, Alembic, Valkey spawn) for a 5-minute local setup.

The wizard records your choice in ~/.workweaver/config.toml so subsequent runs do not re-prompt. Pass ww welcome --reset to re-run, or ww welcome --non-interactive --mode 1|2|3 for scripted automation.

See docs/SELF-HOST.md for the full self-host playbook.

Install The CLI

The default user path is Workweaver Cloud:

python -m pip install workweaver
ww login

On Windows, use the Python launcher:

py -m pip install workweaver
ww login

If the ww script is not on PATH, run the module form instead:

python -m workweaver login

pipx install workweaver is optional when you want an isolated CLI environment, but it is not required for the primary install path. The same wheel exposes ww, workweaver, and python -m workweaver. Repo-local install (python -m pip install -e . from the repo root) still works for active development.

ww login opens the Workweaver sign-in flow and works for both sign-in and sign-up. CLI session metadata and bearer tokens are saved in ~/.workweaver/config.yaml with file mode 0600 by default; the CLI does not touch the OS keyring unless an operator explicitly sets WW_ALLOW_KEYRING=1 and installs the optional keyring extra.

For users who do not want to sign in with workweaver.ai, choose the standalone self-host path:

ww init --email operator@local --password "SelfHost1!" --tenant-name "My Workspace"
ww start

My Workspace is only the default tenant display name. Workweaver config and data default under the current user's ~/.workweaver directory, and CLI commands can point at another config file with --config /path/to/config.yaml.

Packaged-install path is live on PyPI: https://pypi.org/project/workweaver/.

PyPI release automation lives in .github/workflows/release-pypi.yml. Tags matching pyproject.toml pre-release versions (e.g. v0.1.0a1) publish to TestPyPI; final versions (e.g. v0.1.1) publish to PyPI. Both indices use Trusted Publishing/OIDC; no API tokens live in the repo.

Release operators use the guarded repo targets instead of hand-rolling tags:

VERSION=0.1.1 make release-python-prepare
VERSION=0.1.1 make release-python-check
VERSION=0.1.1 make release-python-tag
VERSION=0.1.1 make release-python-smoke-public

Validate the latest prerelease against TestPyPI:

python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ workweaver

Then verify the installed CLI contract:

ww --version
ww mode --output json
ww inference --help

For self-host runtime changes, verify the local backend contract:

curl http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/dashboard

Docker self-host proof path:

make self-host-smoke

The self-host smoke starts Postgres, Valkey, and the backend with no AWS credentials, verifies the self_host_production profile, dashboard serving, WorkMemory remember/recall, and mission/task read paths. If Docker is not available it skips cleanly unless SELF_HOST_SMOKE_REQUIRED=1 is set.

Cost posture proof path:

make cost-guard

The cost guard checks the committed deployment-profile ceilings, managed cost_tier Terraform controls, and AWS resource-type cost-review coverage without calling paid cloud APIs.

Fast deterministic unit proof path:

make test-unit-fast

This runs tests/unit/ with pytest-xdist --dist loadfile, -n auto, --timeout=120, no coverage, and no pytest cache. By default it uses the shared unit-test interpreter at /Users/santhanakrishnan/Documents/Coding/workweaver/.venv/bin/python; set UNIT_PYTHON=/path/to/python when running from another machine or worktree. Use it for the canonical local unit-health signal. Keep make test-unit for coverage diagnostics and make enforce-coverage for the coverage gate.

Canonical architecture and product truth live in:

• policy/docs-index.yaml
• docs/RUNTIME.md
• docs/PRODUCT.md

Provision recall benchmarks: see docs/setup/MEMORYBENCH-PROVISIONING.md for the Bedrock Kimi canonical path (nightly CI, manual workflow dispatch, or make memory-bench-local).

The managed SaaS runtime direction is frozen in docs/RUNTIME.md:

• serverless edge compute for the public path
• portable relational core for stateful intelligence
• provider-specific adapters only at the boundary