Giterloper

Giterloper manages git-based knowledge stores. It runs from this repository.

Specs, tests, and code

This README is human onboarding for the repo layout. Product behavior is defined under specs/; the slice → spec path → test folder index is specs/README.md. For motivation and typical agent workflows (non-normative vision), see docs/use-cases.md. tests/ holds the executable harness and topic slices; see tests/README.md. Implementation lives primarily in lib/ (CLI and MCP server).

For AI agent and contributor workflow, contract pointers, and conventions, see AGENTS.md.

What's here

• Constitution — docs/CONSTITUTION.md defines the contract between Giterloper and knowledge stores. Use gl install-remote <pin> to copy it to a pin as GITERLOPER.md.
• gl skill — .cursor/skills/gl/ provides the CLI for managing knowledge stores.
• MCP server — Giterloper can run as an HTTP/SSE MCP server for version-pinned retrieval and knowledge intake. Indexing (when implemented) is isolated per pin+sha via memsearch; no cross-version index reuse. Normative MCP behavior: MCP row in specs/README.md.

Knowledge stores

Knowledge lives in separate repositories. The default store is giterloper_knowledge. Store connections are defined per session in .giterloper/<sessionId>/pinned.yaml:

my_pin:
  repo: github.com/owner/repo
  sha: <40-char-commit-sha>
  branch: optional-branch-name # omit for read-only pin

Each pin uses an exact commit SHA. The CLI defaults to session _cli (override with --session-id). Cloned stores live under .giterloper/<sessionId>/versions/<name>/<sha>/. Temporary write clones use .giterloper/<sessionId>/staged/<name>/<branch>/.

Quick start

1. Prerequisites: git, Deno, and Python 3 (for memsearch). deno task check, deno task test, deno task mcp:serve, and ./scripts/check_all.sh auto-provision .venv + memsearch when needed; raw deno run lib/gl-mcp-server.ts without scripts/with-memsearch.ts still requires memsearch on PATH at MCP server startup (see MCP slice in specs/README.md). See AGENTS.md and tests/README.md.
2. Add a pin: ./.cursor/skills/gl/scripts/gl pin add <name> <source> [--ref <ref>] [--branch <branch>] (clones automatically).
   • Or load existing pins: ./.cursor/skills/gl/scripts/gl pin load (or --pin <name> for one).
3. Verify: ./.cursor/skills/gl/scripts/gl diagnostic.

Run environment: Development and tests use native Deno (and git) on the host for fast feedback. Default deno task / check_all paths bootstrap memsearch into .venv when missing (see AGENTS.md). Docker is for production (Fly.io) and optional local run when you want to match the container environment.

Docker (production and optional local run)

Production deploys use the Docker image on Fly.io. To run the MCP server in Docker locally (e.g. to match production): ./scripts/run-docker.sh --build. See docs/FLY_IO_DEPLOYMENT.md for Fly.io deploy and local Docker details.

Tests

Run the full suite (typecheck + unified test harness). The harness bootstraps memsearch when needed; you need Python 3 on PATH (see AGENTS.md, tests/README.md).

./scripts/check_all.sh
# or: deno task check

Run only automated tests (same harness as CI):

deno run -A scripts/run-tests.ts
# or: deno task test

Harness lock probes (orchestrator metadata only; no flock acquisition, no kill/timeouts): deno task harness:status and deno task harness:wait-for-idle — see tests/README.md.

Topic-only slices: deno task test:core, deno task test:cli, deno task test:mcp, deno task test:pin-semantics — each sets GITERLOPER_MCP_TEST_SESSION_PARENT for its deno test child via scripts/deno-test-topic.ts (see tests/README.md → Topic tasks and manual deno test (bypass)).

See tests/README.md for the target runner (bounded parallel logical cases, flattened .giterloper/<sessionId>/ layout, test-scoped cleanup) and collision-avoidance rules.