gjalla 0.6.0

gjalla CLI — visibility and control for your software architecture.

Gjalla CLI

Visibility and control for your software architecture. Agentic engineering made magical.

Installation

pip install gjalla

Requires Python >= 3.10.

Commands

Command	Description
setup	Set up gjalla in a repository (interactive wizard, or use subcommands)
status	Show configuration status
state	Navigate project state (architecture, tech stack, capabilities, etc.)
rules	View and manage project rules, principles, ADRs, and invariants
attest	Create commit attestation (interactive or programmatic)
check	Validate commit attestation (used by pre-commit hook)
skills	View project skills (list, filter by category/persona, show detail)
sync	Upload pending attestations and refresh local cache
project	Manage gjalla projects

---

User Guide

Initial Setup

gjalla setup

Launches the interactive wizard:

1. Check git repository
2. Configure API key
3. Verify API key
4. Select project
5. Create .gjalla/ project config
6. Install commit attestation guardrails
7. Install MCP server for Claude Code

Non-interactive subcommands:

gjalla setup auth <api-key>         # Save and verify an API key
gjalla setup project <pid>          # Link this repo to a project
gjalla setup project --check-access # List accessible projects
gjalla setup hooks                  # Install git hooks
gjalla setup mcp                    # Install MCP server entry

Viewing Project State

gjalla state show                                # List top-level keys with entry counts
gjalla state show -c architecture                # Full architecture section
gjalla state show -c architecture -v             # Architecture + file evidence
gjalla state show -e architecture.api-server     # Drill into a single element
gjalla state show -e architecture.api-server -v  # Element + file evidence
gjalla state show -c tech_stack                  # Tech stack, frameworks, vendors
gjalla state show -c capabilities                # Project capabilities and status
gjalla state show -c data_model                  # Data entities, domains, attributes
gjalla state show -c services                    # External services and integrations
gjalla state show -c surface_area                # API endpoints and auth requirements
gjalla state show --system                       # Cross-project system context

Viewing Project Rules

gjalla rules show                # List rule categories with counts
gjalla rules show -c adr         # Show only ADRs
gjalla rules show -c principle   # Show only principles
gjalla rules show -c invariant   # Show only invariants
gjalla rules add -n "No ORM" -d "Use raw SQL queries"  # Add a rule

Daily Usage

Automatic (via pre-commit hook):

• gjalla check runs on each git commit and validates the attestation

Manual / Agent workflow:

git add <files>
gjalla attest            # interactive mode
git commit -m "message"

Programmatic (for agents/scripts):

gjalla attest \
  --staged-diff-hash $(git diff --staged | shasum -a 256 | cut -d' ' -f1) \
  --agent claude-code --provider anthropic --model claude-opus-4-6 \
  --summary "Added rate limiting to auth endpoints" \
  --provenance '{"type": "spec", "ref": "docs/specs/rate-limiting.md"}' \
  --rules '{"checked": true, "applicable": [...]}' \
  --arch-changes '{"architecture": {"elements": [{"name": "web-api", "change": "modified", ...}], ...}}'

Print attestation template:

gjalla attest --example

Refreshing Cache

gjalla sync

Uploads pending attestations and refreshes the local cache from the remote server.

Checking Status

gjalla status

Shows: git repo, global config, API key, project mapping, project config, guardrails, telemetry, attestation log.

Viewing Skills

gjalla skills show                        # List all enabled skills
gjalla skills show --category context     # Filter by category
gjalla skills show --persona code-reviewer # Filter by persona
gjalla skills show analyze-before-coding  # Show full skill content

Configuration

Global config: ~/.gjalla/config.yaml

api_key: "your-api-key"
telemetry: true  # opt-in CLI usage analytics

Project config: .gjalla/config.yaml (in repo root)

Environment variables:

• GJALLA_API_KEY — overrides config file API key
• GJALLA_TELEMETRY — 1/0 to override telemetry consent
• SKIP_ATTESTATION — 1 to skip attestation for a commit
• GJALLA_NO_VERIFY — 1 to skip field validation (hash check still runs)

---

Data Collection

Gjalla collects data at three levels: commit attestations, agent session telemetry, and agent memories. All collection is transparent and documented here.

1. Commit Attestations

When: Every git commit (via pre-commit validation + post-commit processing).

What's collected:

Field	Source	Required?
staged_diff_hash	SHA-256 of staged diff	Yes (user computes)
agent	Agent name (e.g., "claude-code")	Yes
agent_provider	Provider (e.g., "anthropic")	Yes
agent_model	Model ID (e.g., "claude-opus-4-6")	Yes
summary	Impact description of the change	Yes
provenance	What prompted this: {type: "spec|ticket|bug-fix|ad-hoc", ref: "..."}	Yes
rules	Rule compliance report: {checked: true, applicable: [...]}	Yes
changes	Architecture changes across 8 primitives (see below)	Yes
timestamp	ISO 8601 timestamp	Auto-generated
developer	{git_author_name, git_author_email} from git config	Auto-detected
agent_session_id	Session/conversation UUID	Auto-detected from agent runtime
telemetry	Session metrics (see section 2)	Auto-extracted

8 architecture primitives tracked in changes: architecture, data_model, data_flows, rules, capabilities, surface_area, external_services, tech_stack. Each is {changed: false} or {changed: true, details: [...]}.

Where stored locally:

• .gjalla/.commit-attestation.yaml — pending attestation (ephemeral, deleted after commit)
• .gjalla/attestations/<commit-hash>.yaml — archived attestation (permanent)
• .gjalla/log.jsonl — one JSON entry per commit with all fields above

Where uploaded: POST /api/agent/projects/{id}/attestations during gjalla sync.

2. Agent Session Telemetry

When: Auto-extracted at commit time from the active agent's local session files.

What's collected:

Field	Claude Code	Gemini CLI	Codex CLI	OpenCode	Aider
Token counts (in/out/cache)	Yes	Yes (OTel)	No	Best-effort	No
Duration (seconds)	Yes	Yes	Yes	Best-effort	No
Model name	Yes	Yes	Yes	Best-effort	Partial
Tool call count	Yes	Yes	No	Best-effort	No
Tool names + categories	Yes	Yes (OTel spans)	Best-effort	Best-effort	Best-effort

Tool categories: builtin (Read, Edit, Bash), mcp (mcp__gjalla__*), skill (Skill tool), agent (Agent tool).

Security: The Claude Code adapter reads session JSONL files with a strict field allowlist (type, message, timestamp, sessionId, durationMs). It never reads message content, tool arguments, tool results, or any user-authored text. Tool names (e.g., "Read", "mcp__gjalla__get_context") are metadata, not content.

Where stored: Embedded in the attestation's telemetry field → same local + upload path as attestations.

3. Agent Memory Collection

When: During gjalla sync, the CLI reads memories from the active agent and uploads them to the platform. It also downloads merged memories from the platform and distributes them to all agents.

What's collected:

Agent	Collection source	What's read
Claude Code	~/.claude/projects/<project>/memory/*.md	YAML frontmatter (name, description, type) + markdown body. Skips MEMORY.md index and gjalla-distributed files.
OpenCode	.opencode/*.db SQLite	Probes for memory/learning tables. Best-effort extraction.
Codex CLI	N/A	No dedicated memory system
Gemini CLI	N/A	No persistent memory system
Aider	N/A	No structured memory system

Memory fields uploaded: key (identifier), content (markdown body), metadata (name, category, source_agent, original_file).

Memory distribution (platform → agents):

Agent	Write target	Format
Claude Code	~/.claude/projects/<project>/memory/gjalla_*.md	Individual YAML-frontmatter markdown files
OpenCode	.opencode/gjalla-memories.md	Consolidated markdown
Cursor	.cursor/rules/gjalla.mdc	Appended to guidance (via <!-- gjalla-start/end --> tags)
Codex	AGENTS.md	Appended to guidance
Gemini	GEMINI.md	Appended to guidance
Copilot	.github/copilot-instructions.md	Appended to guidance

Where stored locally: .gjalla/cache/memories.json

Where uploaded: POST /api/agent/projects/{id}/memories/bulk during gjalla sync.

4. CLI Usage Analytics (opt-in)

When: On each CLI command execution, if the user has opted in.

What's collected: Command name, CLI version, OS, Python version, install ID (persistent UUID), whether a project is linked. Never collects: code, project data, file contents, credentials.

Consent: Prompted on first run. Stored in ~/.gjalla/config.yaml as telemetry: true|false. Override with GJALLA_TELEMETRY=0.

Where sent: POST /api/cli/telemetry (fire-and-forget, 2s timeout). Error tracking via Sentry (same consent gate, 10% sample rate, sensitive keys scrubbed).

Local Storage Structure

.gjalla/                              # Project root (gitignored)
├── config.yaml                       # Project config (project_id, api_key)
├── .commit-attestation.yaml          # Pending attestation (ephemeral)
├── example-attestation.yaml          # Template for agents
├── log.jsonl                         # Cumulative attestation log
├── attestations/                     # Archived attestation YAMLs
│   └── <commit-hash>.yaml
└── cache/                            # Pulled from platform by `gjalla sync`
    ├── gjallastate.yaml              # Architecture, capabilities, data model
    ├── gjallarules.yaml              # Rules, principles, ADRs, checks
    ├── gjallamap.yaml                # Element-to-file mappings
    ├── architecture.txt              # Rich-formatted architecture overview
    ├── rules.md                      # Markdown-formatted rules
    ├── state.json                    # Full project state (JSON)
    ├── context.md                    # Agent guidance from platform
    ├── skills/                       # Available project skills (one .md per skill)
    │   └── <slug>.md
    ├── memories.json                 # Merged memories from all agents
    ├── system-context.md             # Cross-project context
    ├── system-mappings.yaml          # Cross-project element mappings
    └── specs/                        # Domain behavioral specs
        └── <domain>/spec.md

~/.gjalla/                            # Global config
└── config.yaml                       # API key, telemetry consent, install ID

---

Questions or feedback: [e-mail]