Metadata-Version: 2.4
Name: gjalla
Version: 0.7.8
Summary: gjalla CLI — visibility and control for your software architecture.
License: Proprietary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: gitpython>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.25
Requires-Dist: packaging>=21.0
Requires-Dist: pathspec>=0.11
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: vulture>=2.11; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: monitor
Requires-Dist: watchdog>=3.0; extra == "monitor"
Provides-Extra: bootstrap
Requires-Dist: websockets>=12.0; extra == "bootstrap"
Dynamic: license-file

<!-- mcp-name: io.gjalla/mcp-server -->
# Gjalla CLI

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

## Installation

```bash
pip install gjalla
```

Requires Python >= 3.10.

## Commands

| Command | Description |
|---------|-------------|
| `auth login` | Browser-backed sign in — saves a user-scoped API key locally |
| `setup` | Set up gjalla in a repository (interactive wizard, or use subcommands) |
| `log` | Semantic change history — what primitives changed, when, and by whom |
| `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

### Getting Started

```bash
gjalla auth login       # browser-backed sign in (one command)
gjalla setup            # link a project + install hooks + MCP server
```

`auth login` opens your browser to approve the request. Once approved, a
user-scoped API key is saved locally and works for every project your
account can access.

`setup` launches the interactive wizard:
1. Check git repository
2. Verify API key (or prompt to run `auth login`)
3. Select or create a project
4. Create `.gjalla/` project config
5. Install commit attestation guardrails
6. Install MCP server for Claude Code

**Non-interactive subcommands:**

```bash
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

```bash
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

```bash
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:**
```bash
git add <files>
gjalla attest            # interactive mode
git commit -m "message"
```

**Programmatic (for agents/scripts):**
```bash
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:**
```bash
gjalla attest --example
```

### Refreshing Cache

```bash
gjalla sync
```

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

### Checking Status

```bash
gjalla status
```

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

### Viewing Skills

```bash
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`
```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: hello@gjalla.io
