# AGENTS.md

This file provides repository-level guidance for AI coding agents working on `ossctx`.

## What this project is

`ossctx` is a unified Python CLI for three local context systems:

- `codectx` for source indexing and graph queries
- `docsctx` for document ingestion, crawling, analysis, and retrieval
- `otelctx` for telemetry ingestion, search, and observability APIs

The `common` package contains shared CLI, server, config, middleware, and database helpers used by all three subsystems.

## Core commands

Install:

```bash
python -m pip install -e .
python -m pip install -e .[dev,tree-sitter,loaders]
```

Run tests:

```bash
python -m pytest -q
```

Verified in this repo:

```bash
d:/Development/omni-agents/.venv/Scripts/python.exe -m pytest -q
```

Useful CLI smoke tests:

```bash
ossCtx --version
ossCtx code index . --db .codecontext.db
ossCtx docs stats --db .docscontext.db
ossCtx otel stats --db .otelcontext.db
```

## Repository layout

- `common/` shared version, config, db, server, and middleware helpers
- `codectx/` code indexer, parser registry, repository, HTTP API, and MCP server
- `docsctx/` loader, indexer, analysis, provider integration, HTTP API, and MCP server
- `otelctx/` ingest pipeline, repository, HTTP API, realtime, archive, sampler, TSDB, and MCP server
- `tests/` pytest coverage for all subsystems
- `pyproject.toml` package metadata, dependencies, extras, and console scripts

## Conventions

1. Keep changes minimal and local to the subsystem being modified.
2. Prefer updating README and tests when user-facing behavior changes.
3. Match existing CLI behavior and naming instead of inventing new command patterns.
4. Use SQLite defaults and Pydantic settings models unless the task explicitly requires a new config path.
5. Do not remove compatibility aliases: `codecontext`, `docscontext`, `otelcontext`.
6. When documenting commands, keep examples practical and consistent with implemented defaults.

## Subsystem notes

### CodeCtx

- Main CLI file: `codectx/cli.py`
- Default DB: `.codecontext.db`
- Default HTTP port: `8080`
- Main workflows: `index`, `query`, `stats`, `clean`, `serve`, `mcp`, `setup`

### DocsCtx

- Main CLI file: `docsctx/cli.py`
- Default DB: `.docscontext.db`
- Default HTTP port: `8090`
- Main workflows: local indexing, URL crawling, finalize, stats, serve, MCP, setup
- Optional provider behavior is controlled through `DOCSCTX_*` environment variables

### OtelCtx

- Main CLI file: `otelctx/cli.py`
- Default DB: `.otelcontext.db`
- Default HTTP port: `8088`
- Default OTLP gRPC port: `4317`
- Main workflows: ingest, stats, serve, MCP, setup
- Includes archive, DLQ, TSDB, graph, websocket, and optional Prometheus support

## Documentation expectations

If you add or change commands, configuration, or operator-facing behavior, update:

- `README.md` for user-facing usage
- tests when behavior is observable
- this file if the change affects agent workflows across the repo

## Validation expectations

Before finishing a non-trivial task, prefer one or more of:

- `python -m pytest -q`
- targeted pytest runs for touched areas
- CLI help or smoke commands for changed command surfaces

## Packaging metadata

Console scripts defined in `pyproject.toml`:

- `ossCtx`
- `codecontext`
- `docscontext`
- `otelcontext`