AgilePlus

Appearance

Environment Variables Reference ​

Complete reference of all environment variables affecting AgilePlus behavior.

Core Configuration ​

AGILEPLUS_PROJECT ​

bash
AGILEPLUS_PROJECT=/path/to/project agileplus specify 001-feature
ValueDefaultDescription
Path. (current directory)Project root directory

Used by all commands to locate the git repository and .agileplus/ configuration.

AGILEPLUS_CONFIG ​

bash
AGILEPLUS_CONFIG=/custom/path/config.toml agileplus plan 001-feature
ValueDefaultDescription
Path.kittify/config.tomlConfiguration file location

Allows using a custom configuration file instead of default location.

AGILEPLUS_DATABASE or AGILEPLUS_DB ​

bash
AGILEPLUS_DB=/tmp/agileplus.db agileplus specify 001-feature
ValueDefaultDescription
Path.agileplus/agileplus.dbSQLite database file path

Overrides the --db CLI flag. Useful for in-memory testing (sqlite://) or remote databases.

AGILEPLUS_LOG_LEVEL ​

bash
AGILEPLUS_LOG_LEVEL=debug agileplus specify 001-feature
ValueDescription
traceMost verbose; all function calls and data
debugDetailed diagnostic information
infoGeneral operational information (default)
warnWarning messages for potential issues
errorOnly error messages

Equivalent to CLI -v flags but takes precedence.

AGILEPLUS_NO_COLOR ​

bash
AGILEPLUS_NO_COLOR=1 agileplus queue list
ValueEffect
0 or unsetColored output enabled
1 or trueColored output disabled

Respects the NO_COLOR standard for Unix tools.

AGILEPLUS_VERBOSE ​

bash
AGILEPLUS_VERBOSE=2 agileplus implement 001-feature
ValueEquivalent
0info level
1debug level
2trace level

Alternative to AGILEPLUS_LOG_LEVEL for programmatic control.

Storage Backend ​

Storage Type Selection ​

Default is SQLite, but can be overridden:

bash
AGILEPLUS_STORAGE_TYPE=postgres \
AGILEPLUS_STORAGE_URL="postgresql://user:pass@localhost/agileplus" \
agileplus specify 001-feature
VariableValuePurpose
AGILEPLUS_STORAGE_TYPEsqlite (default), postgres, mysqlDatabase backend
AGILEPLUS_STORAGE_URLConnection stringDatabase connection details

SQLite: sqlite:///path/to/db.db or sqlite:// (in-memory)

PostgreSQL: postgresql://user:pass@host:5432/dbname

MySQL: mysql://user:pass@host:3306/dbname

API & Server Configuration ​

gRPC Server ​

bash
AGILEPLUS_GRPC_HOST=0.0.0.0 \
AGILEPLUS_GRPC_PORT=9090 \
agileplus serve grpc
VariableDefaultDescription
AGILEPLUS_GRPC_HOST127.0.0.1Bind address (localhost-only by default)
AGILEPLUS_GRPC_PORT50051Listen port
AGILEPLUS_GRPC_TLS_CERT—Path to TLS certificate (for HTTPS)
AGILEPLUS_GRPC_TLS_KEY—Path to TLS private key

API Authentication ​

bash
AGILEPLUS_API_TOKEN="sk-proj-abc123..." \
AGILEPLUS_API_TOKEN_EXPIRY=86400 \
agileplus serve grpc
VariableRequiredDescription
AGILEPLUS_API_TOKEN✓ for authBearer token for gRPC requests
AGILEPLUS_API_ALLOW_ANONYMOUS—Allow unauthenticated requests (dev only)
AGILEPLUS_API_TOKEN_EXPIRY—Token lifetime in seconds (default: no expiry)

HTTP/REST API ​

bash
AGILEPLUS_HTTP_HOST=0.0.0.0 \
AGILEPLUS_HTTP_PORT=8080 \
agileplus serve http
VariableDefaultDescription
AGILEPLUS_HTTP_HOST127.0.0.1Bind address
AGILEPLUS_HTTP_PORT8080Listen port
AGILEPLUS_HTTP_CORS_ORIGIN*CORS allowed origin

VCS Configuration ​

Git Repository ​

bash
AGILEPLUS_REPO=/path/to/repo agileplus plan 001-feature
VariableDefaultDescription
AGILEPLUS_REPOcurrent directoryGit repository root

Equivalent to CLI --repo flag. Useful for CI/CD environments.

Worktree Directory ​

bash
AGILEPLUS_WORKTREE_DIR=.worktrees agileplus implement 001-feature
VariableDefaultDescription
AGILEPLUS_WORKTREE_DIR.worktreesDirectory for git worktrees
AGILEPLUS_WORKTREE_AUTO_CLEANUPtrueAuto-remove worktrees on completion

Git Author (for Commits) ​

bash
AGILEPLUS_GIT_AUTHOR_NAME="Claude Code" \
AGILEPLUS_GIT_AUTHOR_EMAIL="claude@anthropic.com" \
agileplus implement 001-feature
VariableDefaultDescription
AGILEPLUS_GIT_AUTHOR_NAMEgit config user.nameCommit author name
AGILEPLUS_GIT_AUTHOR_EMAILgit config user.emailCommit author email

Integration & Sync ​

GitHub ​

bash
GITHUB_TOKEN="ghp_..." \
GITHUB_OWNER="phenotype" \
GITHUB_REPO="agileplus" \
agileplus ship 001-feature
VariableRequiredDescription
GITHUB_TOKEN✓ for syncPersonal access token (scope: repo, workflow)
GITHUB_OWNER✓ for syncRepository owner (user or org)
GITHUB_REPO✓ for syncRepository name
GITHUB_API_BASE—Custom GitHub API URL (for GitHub Enterprise)

GitHub Actions (CI/CD) ​

Automatically set by GitHub Actions runner:

bash
GITHUB_ACTIONS=true              # Running in Actions
GITHUB_REPOSITORY=owner/repo     # Repo identifier
GITHUB_SHA=abc123...             # Current commit
GITHUB_REF=refs/heads/main       # Current branch

Plane.so Integration ​

bash
PLANE_API_KEY="..." \
PLANE_WORKSPACE="my-workspace" \
agileplus sync plane 001-feature
VariableRequiredDescription
PLANE_API_KEY✓API key from Plane settings
PLANE_WORKSPACE✓Workspace slug (from URL)
PLANE_API_URL—Custom Plane instance URL
PLANE_SYNC_BIDIRECTIONAL—Enable two-way sync (default: one-way)

Jira Integration ​

bash
JIRA_URL="https://company.atlassian.net" \
JIRA_USER="user@company.com" \
JIRA_API_TOKEN="..." \
JIRA_PROJECT_KEY="AP" \
agileplus sync jira 001-feature
VariableRequiredDescription
JIRA_URL✓Jira instance URL
JIRA_USER✓Jira email/username
JIRA_API_TOKEN✓API token (from Jira account settings)
JIRA_PROJECT_KEY✓Project key (e.g., AP, INFRA)

Agent Dispatch ​

Agent Selection ​

bash
AGILEPLUS_AGENT="claude-code" \
AGILEPLUS_AGENT_TIMEOUT="3600" \
agileplus implement 001-feature
VariableDefaultDescription
AGILEPLUS_AGENTclaude-codeDefault agent harness to use
AGILEPLUS_AGENT_TIMEOUT1800Agent session timeout in seconds
AGILEPLUS_AGENT_MAX_RETRIES5Max review/fix cycles

Claude Code ​

bash
CLAUDE_CODE_PATH="/usr/local/bin/claude" \
CLAUDE_API_KEY="..." \
agileplus implement 001-feature
VariableDefaultDescription
CLAUDE_CODE_PATHclaude (on PATH)Path to Claude Code binary
CLAUDE_API_KEY—API key for Claude (if needed)

Codex ​

bash
CODEX_API_KEY="..." \
CODEX_ENDPOINT="https://api.openai.com/v1" \
agileplus implement 001-feature --agent codex
VariableDefaultDescription
CODEX_API_KEY—OpenAI API key
CODEX_ENDPOINThttps://api.openai.com/v1Custom endpoint
CODEX_MODELgpt-4Model version

Cursor ​

bash
CURSOR_PATH="/Applications/Cursor.app/Contents/MacOS/Cursor" \
agileplus implement 001-feature --agent cursor
VariableDefaultDescription
CURSOR_PATHcursor (on PATH)Path to Cursor binary

Observability & Monitoring ​

Logging ​

bash
AGILEPLUS_LOG_FORMAT="json" \
AGILEPLUS_LOG_FILE="/var/log/agileplus.log" \
agileplus specify 001-feature
VariableDefaultDescription
AGILEPLUS_LOG_FORMATtexttext or json
AGILEPLUS_LOG_FILEstdoutFile path for logs
AGILEPLUS_LOG_MAX_SIZE100mbRotate log when this size reached
AGILEPLUS_LOG_MAX_AGE30Keep logs for N days

Metrics & Telemetry ​

bash
AGILEPLUS_METRICS_ENABLED="true" \
AGILEPLUS_METRICS_ENDPOINT="http://prometheus:9090" \
agileplus serve grpc
VariableDefaultDescription
AGILEPLUS_METRICS_ENABLEDfalseEnable Prometheus metrics
AGILEPLUS_METRICS_PORT9091Metrics server port
AGILEPLUS_METRICS_ENDPOINT—Push metrics to Prometheus

Tracing (OpenTelemetry) ​

bash
AGILEPLUS_TRACING_ENABLED="true" \
AGILEPLUS_JAEGER_ENDPOINT="http://jaeger:6831" \
agileplus implement 001-feature
VariableDefaultDescription
AGILEPLUS_TRACING_ENABLEDfalseEnable distributed tracing
AGILEPLUS_JAEGER_ENDPOINThttp://localhost:6831Jaeger agent endpoint
AGILEPLUS_TRACE_SAMPLE_RATE0.1Sampling rate (0.0–1.0)

Development & Testing ​

Debug Mode ​

bash
AGILEPLUS_DEBUG="1" \
AGILEPLUS_NO_CLEANUP="1" \
agileplus implement 001-feature
VariableEffect
AGILEPLUS_DEBUG=1Increase verbosity; show detailed errors
AGILEPLUS_NO_CLEANUP=1Don't delete worktrees/artifacts after completion
AGILEPLUS_DRY_RUN=1Simulate commands without executing

Testing ​

bash
AGILEPLUS_TEST_MODE="1" \
AGILEPLUS_TEST_STORAGE="memory" \
cargo test
VariableDescription
AGILEPLUS_TEST_MODE=1Enable test mode (in-memory storage, no git)
AGILEPLUS_TEST_STORAGEsqlite (file), memory, mock
AGILEPLUS_TEST_SEED=12345Seed for reproducible randomness

CI/CD & Automation ​

Continuous Integration ​

bash
AGILEPLUS_CI="1" \
AGILEPLUS_CI_TIMEOUT="600" \
agileplus validate 001-feature
VariableDefaultDescription
AGILEPLUS_CI—Set to 1 to enable CI mode (stricter checks)
AGILEPLUS_CI_TIMEOUT600CI job timeout in seconds
AGILEPLUS_CI_STRICT—Fail on any warning (not just errors)

GitHub Pages (Docs) ​

bash
GITHUB_PAGES="true" \
GITHUB_PAGES_BASEURL="/agileplus" \
agileplus docs build
VariableEffect
GITHUB_PAGES=trueEnable GitHub Pages base path rewriting
GITHUB_PAGES_BASEURL=/repo-nameSet docs base URL

Quick Reference for Common Scenarios ​

Local Development ​

bash
export AGILEPLUS_PROJECT="$(pwd)"
export AGILEPLUS_LOG_LEVEL="debug"
export AGILEPLUS_NO_CLEANUP="1"

CI/CD Pipeline (GitHub Actions) ​

bash
export AGILEPLUS_DB=".agileplus/agileplus.db"
export AGILEPLUS_LOG_LEVEL="info"
export GITHUB_TOKEN="${{ secrets.GITHUB_TOKEN }}"
export AGILEPLUS_CI="1"

Docker Container ​

bash
docker run \
  -e AGILEPLUS_PROJECT=/workspace \
  -e AGILEPLUS_GRPC_HOST=0.0.0.0 \
  -e GITHUB_TOKEN="${GITHUB_TOKEN}" \
  -v /path/to/repo:/workspace \
  agileplus:latest

MCP Server (Agent Integration) ​

bash
export AGILEPLUS_PROJECT="/path/to/project"
export AGILEPLUS_GRPC_HOST="127.0.0.1"
export AGILEPLUS_GRPC_PORT="50051"
export AGILEPLUS_API_TOKEN="$(openssl rand -hex 32)"
agileplus mcp serve

NATS JetStream Configuration ​

When running with the full platform stack:

bash
NATS_URL=nats://localhost:4222 \
NATS_STREAM_NAME=agileplus \
NATS_MAX_AGE=168h \
agileplus platform up
VariableDefaultDescription
NATS_URLnats://localhost:4222NATS server URL
NATS_CREDS—NATS credentials file path (for auth)
NATS_STREAM_NAMEagileplusJetStream stream name
NATS_MAX_AGE168h (7 days)Message retention period
NATS_MAX_BYTES1gbStream storage limit
NATS_REPLICAS1Number of stream replicas (for clustering)

Dragonfly / Redis Configuration ​

bash
DRAGONFLY_URL=redis://localhost:6379 \
DRAGONFLY_MAX_MEMORY=512mb \
agileplus platform up
VariableDefaultDescription
DRAGONFLY_URLredis://localhost:6379Dragonfly/Redis connection URL
DRAGONFLY_PASSWORD—Authentication password
DRAGONFLY_DB0Database number
DRAGONFLY_KEY_PREFIXagileplus:Key namespace prefix
DRAGONFLY_JOB_TTL7200Job state TTL in seconds (2 hours)

Neo4j Configuration ​

bash
NEO4J_URI=bolt://localhost:7687 \
NEO4J_USER=neo4j \
NEO4J_PASSWORD=password \
agileplus platform up
VariableDefaultDescription
NEO4J_URIbolt://localhost:7687Neo4j Bolt protocol URI
NEO4J_USERneo4jNeo4j username
NEO4J_PASSWORD—Neo4j password
NEO4J_DATABASEneo4jDatabase name (Enterprise: any name)
NEO4J_MAX_CONNECTIONS10Connection pool size

MinIO Artifact Storage ​

bash
MINIO_ENDPOINT=http://localhost:9000 \
MINIO_ACCESS_KEY=minioadmin \
MINIO_SECRET_KEY=minioadmin \
MINIO_BUCKET=agileplus-artifacts \
agileplus platform up
VariableDefaultDescription
MINIO_ENDPOINThttp://localhost:9000MinIO server URL
MINIO_ACCESS_KEY—S3 access key ID
MINIO_SECRET_KEY—S3 secret access key
MINIO_BUCKETagileplus-artifactsArtifact storage bucket
MINIO_REGIONus-east-1Region (any value for local MinIO)
MINIO_USE_SSLfalseEnable HTTPS

For AWS S3 instead of MinIO:

bash
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=secret...
AWS_DEFAULT_REGION=us-east-1
MINIO_ENDPOINT=https://s3.amazonaws.com
MINIO_BUCKET=my-agileplus-artifacts
MINIO_USE_SSL=true

Tailscale (P2P Sync) ​

bash
TAILSCALE_AUTH_KEY=tskey-auth-... \
TAILSCALE_HOSTNAME=agileplus-laptop \
agileplus device discover
VariableDefaultDescription
TAILSCALE_AUTH_KEY—Tailscale auth key for device registration
TAILSCALE_HOSTNAMEsystem hostnameDevice name on Tailscale mesh
TAILSCALE_TAGS—ACL tags for the device
AGILEPLUS_P2P_ENABLEDfalseEnable P2P sync via Tailscale
AGILEPLUS_P2P_SYNC_INTERVAL30Seconds between peer sync attempts

Sync Platform Configuration ​

Plane.so ​

VariableRequiredDescription
PLANE_API_KEYYes for syncAPI key from Plane workspace settings
PLANE_WORKSPACEYes for syncWorkspace slug from URL
PLANE_PROJECT—Default project slug
PLANE_API_URL—Custom Plane instance (self-hosted)
PLANE_WEBHOOK_SECRETFor webhooksHMAC secret for webhook validation
PLANE_SYNC_BIDIRECTIONALfalseEnable two-way sync

GitHub ​

VariableRequiredDescription
GITHUB_TOKENYes for syncPAT with repo, workflow scopes
GITHUB_OWNERYes for syncRepository owner (user or org)
GITHUB_REPOYes for syncRepository name
GITHUB_API_BASE—Custom base URL (GitHub Enterprise)
GITHUB_WEBHOOK_SECRETFor webhooksHMAC secret for webhook validation

Complete .env Template ​

bash
# Copy to .env and fill in your values
# Never commit .env to git

# ─── Core ───────────────────────────────────────────────
AGILEPLUS_LOG_LEVEL=info
AGILEPLUS_DB=.agileplus/agileplus.db
AGILEPLUS_WORKTREE_DIR=.worktrees

# ─── Platform Services ──────────────────────────────────
NATS_URL=nats://localhost:4222
DRAGONFLY_URL=redis://localhost:6379
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=change-me
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=change-me

# ─── Sync Integrations ──────────────────────────────────
PLANE_API_KEY=
PLANE_WORKSPACE=
GITHUB_TOKEN=
GITHUB_OWNER=
GITHUB_REPO=

# ─── Agent Dispatch ─────────────────────────────────────
AGILEPLUS_AGENT=claude-code
AGILEPLUS_AGENT_TIMEOUT=1800
CLAUDE_CODE_PATH=claude

# ─── Observability ──────────────────────────────────────
AGILEPLUS_LOG_FORMAT=json
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=agileplus

# ─── API Server ─────────────────────────────────────────
AGILEPLUS_HTTP_HOST=127.0.0.1
AGILEPLUS_HTTP_PORT=8080

Next Steps ​

MIT License

© 2025 Phenotype