Gnosis

Gnosis compiles what you have into what you know.

Gnosis is an enterprise knowledge compiler: a local-first Rust tool that discovers digital objects in a repository, extracts structured knowledge with deterministic providers (Tree-sitter and lightweight document/data parsers), shows its work in a live TUI, and exports an OKF v0.1-style bundle.

This is a proof of concept — not a search engine, vector database, or chat UI.

Install

From crates.io

cargo install gnosis

From source

cargo install --git https://github.com/thanos/gnosis
# or from a checkout:
cargo install --path .

Prebuilt binaries for Linux, macOS, and Windows are attached to GitHub Releases on each v* tag (with SHA256SUMS).

Quick start

cargo build --release
./target/release/gnosis scan ./fixtures/mixed-repo

Headless (CI / scripting):

cargo run -- scan ./fixtures/mixed-repo --no-tui --export

Commands

scan options

Scanning is recursive under <path> (via ignore::WalkBuilder). Descent skips .gitignore matches, target / node_modules / .git / knowledge.okf, and does not follow symlinks.

TUI commands (:)

summary · objects [status] · unknown · providers · stats · find <text> · explain <name> · graph <name> · export okf [path] · quit

Shortcuts: s summary · u unknown · e export · q quit

What you get

1. A live (or printed) inventory of what was understood, partial, unknown, or failed
2. Extracted entities and relationships (functions, classes, modules, documents, CSV columns, …)
3. Optional OKF bundle (knowledge.okf/ by default) — markdown + YAML you can browse, commit, or feed to other tools

Good fit today

• Point at an unfamiliar local Git/repo tree and see structure emerge
• Demo / PoC of “compile repo → structured knowledge”
• Export a portable knowledge directory for humans or agents

Not for yet: cloud buckets, remote-only hosts, PDFs/office, vectors/RAG, or chat (see Limitations).

Library usage

One crate provides both the CLI and the library. Depend on it as:

[dependencies]
gnosis = "0.1"

Public modules include pipeline/store/query APIs plus providers, okf, and tui for embedding.

Headless scan + export sketch:

use gnosis::{
    default_registry, Exporter, OkfExporter, Pipeline, PipelineEvent, QueryEngine, Result,
    ScanConfig,
};

fn main() -> Result<()> {
    let config = ScanConfig::with_root("./my-repo");
    let pipeline = Pipeline::new(config.clone(), default_registry());
    let mut handle = pipeline.spawn();
    let events = handle.take_events();

    while let Ok(ev) = events.recv() {
        if matches!(ev, PipelineEvent::ScanCompleted { .. }) {
            break;
        }
    }
    handle.wait()?;

    let store = handle.store.lock().unwrap();
    print!("{}", QueryEngine::new(&store).summary());
    OkfExporter::new().export(&store, &config.output_path)?;
    Ok(())
}

Typical flow: default_registry() → Pipeline::spawn → observe PipelineEvents / query KnowledgeStore → OkfExporter::export.

Architecture

gnosis (one crate)
├── binary: gnosis
└── library modules:
    ├── connectors, pipeline, store, query
    ├── providers (tree-sitter + docs/data + generic)
    ├── okf (export)
    └── tui (Ratatui UI)

Pipeline: Connector → Discovery → ProtoData → Provider selection → Analysis → Knowledge store → Query / OKF export.

Events flow over a bounded channel so the TUI observes progress without coupling to workers.

What the PoC understands

• Code: C++, Rust, Elixir via Tree-sitter (modules, types, functions, imports/includes, inheritance where syntactic)
• Docs: Markdown, plain text
• Data: JSON, YAML, TOML, CSV (bounded)
• Everything else: honest unknown / partial with metadata and a candidate future provider category

Limitations

• Local filesystem only (no S3, remote Git hosts, web crawl)
• No LLM providers, vectors, or persistent index
• Tree-sitter is syntactic — not compiler-grade semantics
• Git enrichment uses the git CLI when available (not a pure-Rust Git library)
• OKF export is a hand-written markdown+YAML bundle plus sidecar.json (not the okf crates.io crate)
• No gnosis.toml yet — configuration is CLI flags only

Development

cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check
cargo deny check
cargo run -- scan ./fixtures/mixed-repo --no-tui

CI/CD

Secrets / external setup:

• Enable the repo on Coveralls (action uses GITHUB_TOKEN)
• Set CARGO_REGISTRY_TOKEN for crates.io publish on release tags

Releases: see CONTRIBUTING.md. Push an annotated v* tag matching version in Cargo.toml (publishes the single gnosis crate).

Demo

See demo.md.

Changelog

See CHANGELOG.md for release history.

Contributing

See CONTRIBUTING.md for development setup, PR expectations, and the maintainer release checklist.

License

MIT — see LICENSE.