Projects & indexing

Register a folder with orkai init, index code and documents locally, or index a GitHub repo in one command.

A project is any directory registered with orkai. Developers index repos; researchers and analysts index folders of PDFs, CSVs, and notes — the same commands apply.

orkai init

Run once inside a folder. Creates a category in the daemon and writes .orkai.yaml in that directory.

cd /path/to/your/folder
orkai init
orkai init -y
orkai init --starter-pack
orkai init -y --starter-pack

• orkai init asks for a project name, then whether to install the starter pack.
• -y uses the folder name and skips every prompt. No starter pack.
• --starter-pack installs the pack without asking. It works with or without -y.

Requires a running daemon. Re-running on an already-initialized folder prints the existing config and does not install the pack again.

orkai index

Index the current directory (or a path). Settings load from .orkai.yaml; mode subcommands and flags override the file.

orkai index .                 # default: all (code + documents + analytics)
orkai index all .             # same as above, explicit
orkai index code .            # source code and text-code only
orkai index document .        # documents only (.md, .pdf, .docx, …)
orkai index analytics .       # spreadsheets only (.csv, .xlsx, .parquet)
orkai index --stats .         # show index state, do not index
orkai index --dry-run all .   # preview a full index

Index modes

Legacy flags --document and --all still work but are deprecated in favor of orkai index document and orkai index all.

Common flags

Built-in text-code includes json, yaml, sql, sh, css, Makefile, Dockerfile, go.mod, and more.

Index a GitHub repository

Index a public or private GitHub repo without cloning it yourself. orkai shallow-clones to a temporary directory under ~/.orkai/temp, creates or reuses a category named owner/repo, writes .orkai.yaml, runs a full index, then removes the clone.

orkai index --github beforethesprint/orkai
orkai index --github https://github.com/org/repo.git
orkai index --github org/repo@main
orkai index code --github org/repo   # code-only pass

Accepted specs: owner/repo, owner/repo@ref, and HTTPS URLs (with or without a .git suffix). Set GITHUB_TOKEN or GH_TOKEN for private repos. Re-running the same repo updates the existing category instead of creating a duplicate.

This is different from --url below: --github indexes the whole repository (code, documents, analytics). --url fetches individual documents or GitHub tree paths via the GitHub API — useful for skills and standards, not full repos.

Index from a URL

Index a skill, standard, or document from the web — including GitHub tree URLs:

orkai index --url https://example.com/skill/SKILL.md \
  --name "My Skill" --category skills

orkai index --url https://github.com/org/repo/tree/main/skills/my-skill \
  --parent-file SKILL.md --name "My Skill" --entity-type skill --category skills

Use --parent-url or --parent-id to attach indexed URLs as children of an existing entity. GitHub blob URLs are converted to raw content automatically.

orkai unindex

Remove an indexed project and all its entities from the daemon.

orkai unindex my-project
orkai unindex my-project --yes
orkai unindex d5a003d1f642f03946ac5f3798e77569

Accepts category name or ID. Run from any directory. --yes skips the confirmation prompt (same as --force). A non-interactive shell must pass --yes. Otherwise the command exits instead of waiting.

Annotations only

When annotations are enabled in daemon config, re-run the annotation pipeline without a full re-index:

orkai index --annotations-only .

Requires an existing project index. For what annotations, @orkai tags, and enriched source mean, see Knowledge layer.

Sync requirements, architecture, and standards

A knowledge: block in .orkai.yaml tells orkai index to upsert three entity types from markdown in the repo. Those files are not also stored as documents. A later index removes the document copies. Other .md files still index as documents. This sync is not the annotation knowledge layer, and it is not review.knowledge_base.

knowledge:
  architectures: docs/architecture
  requirements: docs/requirements.md
  standards:
    files:
      - docs/standards/a.md

Paths are repo-relative. No absolute paths and no ... A string can be one file or a directory of *.md files. An object lists files. A bare YAML list is an error.

Requirements and architectures have one current file. That file is status: active. The other listed files are indexed, then archived. Set current to one files entry exactly. One file and no current means that file is current. Several files, or a folder of several, with no current is an error. orkai does not guess.

knowledge:
  architectures:
    files:
      - docs/architecture/current.md
      - docs/architecture/old.md
    current: docs/architecture/current.md
  requirements: docs/requirements.md

current is not allowed on standards. Every listed standard stays active.

• Identity is category + type + path, not the title. The file wins on the next index. There is no write-back to the markdown.
• A missing path or a missing current file fails the sync. The previous active entity is not archived.
• A path removed from the block archives only an entity this sync created. Omitting a key does not archive that type. Hand-written entities are left alone.
• The sync runs on every index, including orkai index code. orkai index --dry-run reports the files and does not write.

.orkai.yaml

After the first index, orkai may persist resolved settings in .orkai.yaml. CLI mode subcommands and flags always win over the file. Default mode is index.type: all on new projects (orkai init).

index:
  type: all          # default for bare orkai index
  path: .
  analytics:
    enabled: true     # indexed by all or analytics mode
knowledge:
  requirements: docs/requirements.md
  architectures: docs/architecture.md
  standards: docs/standards

See Sync requirements, architecture, and standards for the knowledge: rules. See orkai help index for the full schema.