Onboarding commands
devvis init
Initialize DevVis in the current project directory.
devvis init <customer-key>
Your DevVis customer key. Find it in the DevVis dashboard under Settings → API Keys.
Creates .devvis/config.json
Saves the customer key at the project level (not machine-level).
Updates .gitignore
Appends .devvis/ to .gitignore, creating the file if it doesn’t exist.
devvis init again overwrites the existing key. The .gitignore entry is not duplicated (idempotent).
devvis update-key
Update the customer key for the current project.
devvis update-key <new-customer-key>
devvis init first.
devvis remove
Remove the DevVis config from the current project.
Deletes .devvis/ from the current directory. Does not affect hooks or other projects. Idempotent.
devvis setup-hooks
Install Claude Code hooks (run once per machine).
Merges DevVis hooks into ~/.claude/settings.json, preserving any existing third-party hooks. Creates a backup at ~/.claude/settings.devvis-backup.json before modifying. Idempotent — will not duplicate hooks already present.
Hooks installed:
| Event | Matcher | What it captures |
|---|
SessionStart | — | Session lifecycle begin |
Stop | — | Session summary + token usage |
PostToolUse | ExitPlanMode | Plan approval |
PostToolUse | TaskCreate | Task creation |
PostToolUse | TaskUpdate | Task completion |
devvis uninstall
Remove hooks and the binary.
Removes DevVis hooks from ~/.claude/settings.json and deletes the binary. Idempotent.
Hook adapter
devvis send-episode
High-level command used by Claude Code hooks. Reads the hook payload from stdin, enriches it with local context, and posts a normalized event to the API.
devvis send-episode --event <event-name> [--customer-key <key>] [--api-url <url>]
The event name to send. See supported events below.
Override the customer key. Defaults to the project-level .devvis/config.json.
Override the API base URL. Defaults to https://devvis.com.br.
--event value | What it captures |
|---|
session-start | Session lifecycle begin; records session ID and working directory |
plan-approved | Plan approval via ExitPlanMode; extracts allowed prompts as plan steps |
task-created | Task creation; caches subject/description for task-completed correlation |
task-completed | Task completion; retrieves cached metadata to build a rich event |
session-summary | Session end; reads the transcript for a summary and sums token usage |
send-episode never fails loudly — all errors are logged to ~/.devvis/hooks.log and the process exits with code 0. This ensures Claude Code’s workflow is never blocked by telemetry failures.
Writer commands
Low-level commands for writing directly to the knowledge graph.
devvis writer add-episode
Write an explicit episode.
devvis writer add-episode \
--name "task_completed:auth-refactor" \
--body '{"summary":"completed auth refactor","files":["api/auth.py"]}' \
--group-id "project-alpha" \
--customer-key <key>
| Flag | Required | Description |
|---|
--name | Yes | Episode name |
--body | No | Episode body (text or JSON); mutually exclusive with --body-file |
--body-file | No | Path to a file containing the episode body |
--group-id | No | Scope/tenant group |
--reference-time | No | ISO 8601 timestamp |
--source-description | No | Source label (default: devvisibility-cli) |
--customer-key | Yes | Customer key (or DEVVIS_CUSTOMER_KEY env var) |
--api-url | No | Override API base URL |
--body and --body-file are both omitted, the body is read from stdin.
devvis writer add-facts
Create an explicit relationship triplet (source → relationship → target).
devvis writer add-facts \
--source "dev:fabio" \
--relationship "COMMITTED" \
--target "commit:abc1234" \
--description "Fabio committed abc1234 in auth module" \
--customer-key <key>
| Flag | Required | Description |
|---|
--source | Yes | Source entity name |
--relationship | Yes | Relationship label |
--target | Yes | Target entity name |
--description | Yes | Fact description |
--group-id | No | Scope/tenant group |
--source-entity-uuid | No | Existing source entity UUID |
--target-entity-uuid | No | Existing target entity UUID |
--customer-key | Yes | Customer key (or DEVVIS_CUSTOMER_KEY env var) |
--api-url | No | Override API base URL |
devvis writer add-entity
Create an entity by writing a synthetic descriptive episode.
devvis writer add-entity \
--name "Authentication Module" \
--type "Component" \
--summary "JWT auth layer for API" \
--customer-key <key>
| Flag | Required | Description |
|---|
--name | Yes | Entity name |
--type | No | Entity type label |
--summary | No | Entity summary |
--group-id | No | Scope/tenant group |
--customer-key | Yes | Customer key (or DEVVIS_CUSTOMER_KEY env var) |
--api-url | No | Override API base URL |
Configuration
devvis config show # Show full resolved configuration
devvis config get api-url # Show configured API URL
devvis config set api-url <url> # Persist API base URL
devvis version
devvis version
# devvis (go) v0.1.0
Authentication
All commands that call the API require a customer key, resolved in this order:
--customer-key flagDEVVIS_CUSTOMER_KEY environment variable.devvis/config.json in the project working directory- Error if none of the above is set
For send-episode (called by hooks), the working directory comes from the cwd field in the Claude Code hook payload — so each project automatically uses its own key without extra configuration.
The key is sent as the X-DevVis-Customer-Key HTTP header on all requests.
Local files
| Path | Purpose |
|---|
<project>/.devvis/config.json | Per-project customer key. Created by devvis init. |
~/.devvis/hooks.log | Hook execution log. Rotated to the last 1000 lines when it exceeds 80 KB. |
~/.devvis/hooks-debug.jsonl | Raw hook payloads in JSONL format (debug). Same rotation policy. |
~/.devvis/task-cache/<id>.json | Ephemeral task metadata for create→complete correlation. Purged on session end. |
~/.claude/settings.json | Global Claude Code settings. devvis setup-hooks adds hooks here. |
