OctoGraph.Cli 0.0.5

OctoGraph

OctoGraph is a local code knowledge graph for repositories and workspaces. It indexes source folders into graph, search, route, tool, contract, context, and impact data for developers and AI agents.

Install (CLI)

dotnet tool install --global OctoGraph.Cli

octograph --help
octograph index --target codex <repository-path>
octograph serve
octograph mcp

The octograph mcp command starts the MCP stdio server used by editors and agents that support MCP.

Local PostgreSQL with Docker

The bundled compose file starts only PostgreSQL with pgvector; run the CLI/API on the host:

# From the repository root:
docker compose up -d postgres

Services:

Persistent volume: postgres_data.

CLI configuration

OctoGraph stores global CLI/API state in %USERPROFILE%\.octograph on Windows, or $HOME/.octograph on Unix. Set OCTOGRAPH_HOME to move that directory.

On first octograph startup, OctoGraph creates the global directory and writes config.json with the default settings. .NET global tools do not execute package code during dotnet tool install, so this initialization happens on the first command invocation after install.

config.json is the only source for database and embedding settings. Edit %USERPROFILE%\.octograph\config.json, or $env:OCTOGRAPH_HOME\config.json if you set OCTOGRAPH_HOME:

{
  "embeddings": {
    "provider": "auto",
    "model": "qwen3-embedding:8b",
    "baseUrl": "http://localhost:11434",
    "apiKeyEnvironmentVariable": "",
    "autoPullOllamaModel": true,
    "dimension": 0,
    "maxInputCharacters": 6000,
    "embeddingBatchSize": 16,
    "embeddingConcurrency": 2,
    "semanticEfSearch": 80
  },
  "postgreSql": {
    "connectionString": "Host=localhost;Port=5432;Database=octograph;Username=postgres;Password=postgres;Pooling=true;Maximum Pool Size=50;Command Timeout=0;Keepalive=30"
  }
}

Production posture

The 0.0.x line is approaching production readiness. The shape today:

• Race-free indexing: concurrent POST /v1/repos/index for the same path are rejected with REPOSITORY_ALREADY_INDEXING (HTTP 409) instead of double-enqueueing. Backed by a uniqueness-constrained octograph.active_index_jobs table.
• Structured errors: the API returns a stable JSON envelope { "error": { "code", "message", "retryable", "details" } } with codes documented in OctoGraph.Core/Errors/OctoGraphErrorCode.cs.
• Retention sweep: a background RetentionMaintenanceService runs hourly to delete terminal-state index jobs older than 7 days and release crashed active-index claims older than 6 hours. Knobs in RetentionOptions.
• Resumable retries: the index job is configured with MaxAttempts = 3. The ParsedFileCache skips re-parsing files whose content hash matches a previous successful parse, so retries are cheap.
• Deferred embeddings (API): indexing returns as soon as the graph and lexical search are ready; embeddings warm asynchronously via EmbeddingWarmupService.QueueWarmAsync. Status is exposed via GET /v1/repos/{name}/embeddings/status. The CLI keeps the inline warm path for one-shot use.
• Structured logging: ILogger<T> is wired into IndexJobService, IndexRepositoryJobHandler, IndexRepositoryService, and EmbeddingWarmupService for lifecycle and failure events.
• Native cross-file graph: there is no SCIP/external-indexer dependency. After parsing, CrossFileLinker resolves reference edges (CALLS, INHERITS, …) to the real definitions they target using import scope, and labels every cross-file edge exact, ambiguous, or unresolved (surfaced on query/references) so agents know how much to trust each edge. Resolution is name-based, not type-aware — overloaded names resolve to ambiguous rather than guessing.
• Safe rename: the rename MCP tool is a word-boundary textual replace (it also touches comments/strings and is not type-aware). It defaults to a dry run that returns per-file hunks; pass apply: true to write. The CLI rename applies by default with a --dry-run preview.

Open items before "ship to the public internet":

• Add authentication middleware to the REST API (no auth is enforced today; deploy only on trusted networks or behind an authenticated reverse proxy).
• Change the jobs-dashboard credentials in Program.cs (currently admin / admin@123).
• Add a schema version table so future CLI upgrades can refuse incompatible indexed repositories cleanly.
• Set up a GitHub Actions release pipeline (build → test → signed NuGet publish).