diff --git a/LICENSE b/LICENSE index 249f0009e..c3c89f4fa 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,8 @@ MIT License -Copyright (c) 2025 Web3 Infrastructure Foundation +Copyright (c) 2025-2026 Web3 Infrastructure Foundation + +Copyright (c) 2026 GitMono Limited Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 0cd5f9656..1cfcc9183 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,135 @@ -![Libra](docs/image/banner.png) +[中文](README.zh-CN.md) | English -Libra is a partial implementation of a **Git** client, developed in **Rust**. The goal is **not** to build a perfect, 100% feature-complete reimplementation of Git (if you want that, take a look at [gitoxide](https://github.com/Byron/gitoxide)). Instead, Libra is evolving into an **AI agent–native version control system**. +![Libra](docs/image/libra-banner.png) -The `libra code` command starts an interactive TUI (with a background web server and an MCP stdio surface) that is designed to be driven collaboratively by AI agents and humans. Libra also ships AI-native subcommands not found in Git: `code-control`, `automation`, `agent`, `usage`, `graph`, `sandbox`, and `publish`. +
---- +# Libra — An AI-native Extended VCS Built for Agents -# AI Features +**Versioning the entire software creation lifecycle, not just code.** -The AI surface is what makes Libra different from a vanilla Git client. The sections below cover where AI data lives, how to drive the AI runtime (`libra code`), which providers are supported, and the Libra-only subcommands that orchestrate the agent. +
-## AI Data Storage +Libra is an AI-native infrastructure that captures and structures the full lifecycle of software development, documenting every step from human intent and AI reasoning to validation and release. -Libra persists AI threads, runs, tasks, decisions, validation reports, tool-invocation events, patchset snapshots, automation history, captured external-agent sessions, and the live context window into the same repository storage directory that holds Git objects. Everything an AI agent does inside a Libra repository is durable, queryable, and replayable — no out-of-band state. +Our mission is to ensure that every software creation becomes lasting knowledge instead of discarded workflow data, empowering developers, teams, and AI systems to retrieve, reuse, and build upon the intelligence behind every piece of software. -### Repository Layout (`.libra/`) +As AI becomes the primary producer of software, Libra provides the foundational infrastructure that preserves, compounds, and unlocks the long-term value of software creation. -``` -.libra/ -├── libra.db # SQLite — Git core + AI threads + AI runtime contracts -├── vault.db # libvault — encrypted secrets (signing keys, provider creds) -├── objects/ # Local object store (loose + pack) — used when no remote backend is configured -├── sessions/ # JSONL session store for AI conversations and file history -└── ai/ # Working files written by the AI runtime -``` +
-If `--separate-libra-dir ` is passed to `libra init`, the entire storage directory is relocated; the working tree only keeps a pointer file. +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![CI](https://github.com/wingwangsz/libra/actions/workflows/base.yml/badge.svg)](https://github.com/wingwangsz/libra/actions/workflows/base.yml) +[![Discord](https://img.shields.io/badge/Discord-join-%235865F2?logo=discord&logoColor=white)](https://discord.gg/MTbb5rDYsC) +[![X](https://img.shields.io/badge/X-%40git_mono_AI-%231DA1F2?logo=x&logoColor=white)](https://x.com/git_mono_AI) +[![Docs](https://img.shields.io/badge/docs-docs.libra.tools-29B1FF)](https://docs.libra.tools) -### SQLite Schema Groups +
-The single `libra.db` carries three logical schema groups (canonical bootstrap files: `sql/sqlite_20260309_init.sql` and `sql/sqlite_20260415_ai_runtime_contract.sql`; versioned forward + `_down.sql` migrations live in `sql/migrations/`): - -| Group | Tables | -|-------|--------| -| Git core | `config`, `config_kv`, `reference`, `reflog`, `rebase_state`, `object_index`, `schema_version` | -| AI threads & scheduling | `ai_thread`, `ai_thread_participant`, `ai_thread_intent`, `ai_thread_provider_metadata`, `ai_scheduler_state`, `ai_scheduler_plan_head`, `ai_scheduler_selected_plan`, `ai_live_context_window` | -| AI runtime contracts | `ai_index_intent_plan`, `ai_index_intent_task`, `ai_index_intent_context_frame`, `ai_index_plan_step_task`, `ai_index_run_event`, `ai_index_run_patchset`, `ai_index_task_run`, `ai_decision_proposal`, `ai_risk_score_breakdown`, `ai_validation_report` | - -The publish Worker uses its own D1 schema in `sql/publish/` (independent from `libra.db`). +--- -### Inspecting AI Data +## Key Differentiators -Every AI record is addressable via `cat-file`'s AI selectors. Pair with `--json=pretty` for machine-readable output: +| Capability | Traditional VCS (Git) | Libra | +|-----------|----------------------|-------| +| **Versioned Artifacts** | Source code only | Code + AI reasoning + decisions + validation reports + session transcripts | +| **AI Collaboration** | Manual commit messages | Native AI agent threads with full audit trail | +| **Knowledge Reuse** | Code snapshots | Reusable intelligence assets across projects | +| **Security** | External GPG/SSH setup | Built-in vault with per-repo key isolation | +| **Provider Lock-in** | N/A | 7+ AI providers, switch freely | +| **Automation** | External CI/CD | Built-in cron-driven agent automation | -```bash -libra cat-file --ai-list ai_session # List captured AI sessions -libra cat-file --ai-list run # Runs (one per agent invocation) -libra cat-file --ai-list task # Tasks within a plan -libra cat-file --ai-list tool_invocation_event # Every tool call the agent issued -libra cat-file --ai-list patchset_snapshot # Patchset diffs proposed by the agent -libra --json=pretty cat-file --ai ai_session: - -libra graph [--repo /path/to/repo] # TUI: navigate an AI thread version graph -libra usage # Token + cost summary per provider/model -libra --json=pretty usage -libra db status # Schema version and migration status -``` +--- -### Tiered Object Storage (S3 / R2 / MinIO) +## Quick Start -Libra can offload large objects (commits, blobs, packs, AI patchset snapshots) to S3-compatible object storage while keeping a local LRU cache. Tiering rules: +### Install -- **Small objects** (`< LIBRA_STORAGE_THRESHOLD`) — stored in both local and remote storage. -- **Large objects** (`≥ LIBRA_STORAGE_THRESHOLD`) — stored remotely with a local LRU cache. +```bash +# macOS / Linux (recommended) +curl -fsSL https://download.libra.tools/install.sh | sh -If `LIBRA_STORAGE_TYPE` is not set, Libra uses local-only storage under `.libra/objects`. +# Homebrew (macOS) +brew install libra -| Variable | Description | Required (for S3/R2) | Default | -|-----------------------------|---------------------------------------------------------------|----------------------|----------------------| -| `LIBRA_STORAGE_TYPE` | Storage backend type: `s3` or `r2` | Yes | – | -| `LIBRA_STORAGE_BUCKET` | Bucket name | Yes | `libra` | -| `LIBRA_STORAGE_ENDPOINT` | S3-compatible endpoint URL (required for R2) | Yes (for R2) | AWS S3 default | -| `LIBRA_STORAGE_REGION` | Region for bucket | No | `auto` | -| `LIBRA_STORAGE_ACCESS_KEY` | Access key ID | Yes | – | -| `LIBRA_STORAGE_SECRET_KEY` | Secret access key | Yes | – | -| `LIBRA_STORAGE_THRESHOLD` | Size threshold in bytes for tiering | No | `1048576` (1 MB) | -| `LIBRA_STORAGE_CACHE_SIZE` | Local cache size limit in bytes | No | `209715200` (200 MB) | -| `LIBRA_STORAGE_ALLOW_HTTP` | Allow HTTP (non-TLS) endpoints for testing (not for prod) | No | `false` | +# From source (requires Rust) +git clone https://github.com/wingwangsz/libra.git +cd libra +cargo build --release +``` -> If any mandatory variable is invalid or empty, Libra automatically falls back to local storage and logs an error. +### Initialize Your First Repository -### Cloud Backup & Restore (Cloudflare D1 + R2) +```bash +# Create a new Libra repository +libra init my-project +cd my-project -`libra cloud` backs up the full repository state — Git objects, refs, **and** all AI tables — to Cloudflare D1 (metadata) plus R2 (objects). This is the canonical way to move a Libra repository (including its AI history) between machines. +# Or convert an existing Git repository +libra init --from-git-repository /path/to/existing/git/repo +``` -| Variable | Description | Required | -|----------|-------------|----------| -| `LIBRA_D1_ACCOUNT_ID` | Cloudflare Account ID | Yes | -| `LIBRA_D1_API_TOKEN` | Cloudflare API Token | Yes | -| `LIBRA_D1_DATABASE_ID` | Cloudflare D1 Database ID | Yes | +### Use Agent Capture ```bash -libra cloud sync # Sync local repository (incl. AI data) to D1/R2 -libra cloud restore --name # Restore by project name -libra cloud restore --repo-id # Restore by repo ID -libra cloud status # Show synchronization status - -libra config cloud.name # Override the default (directory name) project name -``` +# Enable capture hooks for your agent (e.g., codex) +libra agent enable -### Vault-Backed Secrets +# Run your agent tool normally — Libra captures sessions and checkpoints +codex -`vault.db` (powered by [`libvault`](https://crates.io/crates/libvault)) stores AI provider keys, commit-signing GPG/SSH material, and arbitrary secrets used by the `automation` runtime. The unseal key is held outside the repository at `~/.libra/vault-keys/`; the encrypted root token is recorded in repository config (`vault.roottoken_enc`). +# Inspect captured sessions +libra agent session list +libra agent checkpoint list +``` -Vault is enabled by default for every `libra init`; see [Vault-Backed Signing](#vault-backed-signing) for details. +> See [Agent Capture documentation](https://docs.libra.tools/en/docs/getting-started/agent) for all supported agents, advanced configuration, and session management. --- -## Libra Code Modes +## Core Features -Libra Code supports three operation modes, each designed for different use cases. +### 🧠 AI-Native Threading & Persistence -### 1. TUI Mode (Default) +Every AI agent session is a first-class citizen in Libra. Threads, plans, tasks, decisions, validation reports, tool invocations, and patchset snapshots are all persisted directly in the repository alongside your code. No out-of-band state — everything is durable, queryable, and replayable. -Starts an interactive Terminal User Interface along with a background web server. -This is the standard mode for developers who want to work directly in the terminal with AI assistance. - -```bash -libra code +``` +.libra/ +├── libra.db # SQLite: Git core + AI threads + runtime contracts +├── vault.db # Encrypted secrets (provider keys, signing keys) +├── objects/ # Object store (loose + pack, compatible with Git) +├── sessions/ # AI conversation transcripts in JSONL +└── ai/ # AI runtime working files ``` -- **Storage**: Uses the local project directory (`.libra/`) to isolate history and context per project. +### 🔄 Git-Compatible Foundation -### 2. Web Mode +Libra speaks Git's language. On-disk formats (objects, index, pack, pack-index) and wire protocols are fully compatible with standard Git servers (GitHub, GitLab, Gitea, etc.). You can `push` and `pull` to any Git remote with zero friction. -Runs only the web server without the TUI. -Useful for remote development or when you prefer using the browser interface exclusively. +Key difference: Git manages files. Libra manages **creation**. -```bash -libra code --web -``` +### 🔐 Vault-Backed Security -- **Storage**: Uses the local project directory (`.libra/`). +Every `libra init` automatically creates a per-repository vault for encrypted key management: +- **GPG signing keys** for commit verification +- **SSH keys** for remote authentication +- **AI provider credentials** securely stored -### 3. Stdio Mode (MCP) +No external key management setup required. Keys are isolated per repository and never leave the vault. -Runs the Model Context Protocol (MCP) server over standard input/output. -This mode is designed for integration with AI clients like **Claude Desktop**. +### 🛡️ Command Safety Sandbox -```bash -libra code --stdio -``` +Every tool invocation from an AI agent passes through a configurable safety sandbox with command preflight checks, network policy enforcement, and optional seccomp/seatbelt restrictions. Define what agents can and cannot do. -- **Storage**: Uses the local project directory (`.libra/`) for history persistence (same as TUI/Web modes). - The directory must be writable by the calling process (including sandboxed desktop AI apps). +### ☁️ Tiered Cloud Storage & Backup -#### Claude Desktop Configuration +- **Tiered storage**: Offload large objects to S3/R2/RustFS with local LRU caching +- **Cloud backup**: Sync your entire repository state (including AI history) to Cloudflare D1 + R2 +- **Portable**: Move a Libra repository between machines with all AI context intact -To use Libra with Claude Desktop, you must configure the MCP server to run within a valid Libra repository. -Update your `claude_desktop_config.json` as follows: +### 🌐 MCP Protocol Native + +Libra natively supports the [Model Context Protocol](https://modelcontextprotocol.io/), enabling direct integration with Claude Desktop, Cursor, and any MCP-compatible client. Configure once, use everywhere. ```json { @@ -162,477 +143,29 @@ Update your `claude_desktop_config.json` as follows: } ``` -> **Note**: The `cwd` (current working directory) must be set to the root of a valid Libra repository. -> If `libra code` is launched outside of a repository, it will exit with an error. - -#### Managed Runtime Migration - -The legacy `claudecode` provider was removed. Use `libra code --provider codex` -for Libra's managed agent runtime, or `libra code --provider anthropic` for -direct Anthropic chat completions. Claude provider-session flags such as -`--resume-session`, `--fork-session`, `--session-id`, and `--resume-at` are no -longer accepted; use Libra's canonical `--resume ` flow for persisted -sessions. - -## AI Provider Selection - -Libra Code supports multiple AI provider backends. Use the `--provider` and `--model` flags to choose which LLM to use: - -```bash -# Gemini (default) -libra code --provider gemini -libra code --provider gemini --model gemini-2.5-flash - -# OpenAI -libra code --provider openai --model gpt-4o - -# Anthropic (direct chat completions) -libra code --provider anthropic --model claude-sonnet-4-6 - -# DeepSeek -libra code --provider deepseek -libra code --provider deepseek --model deepseek-v4-pro --deepseek-thinking enabled --deepseek-reasoning-effort high -libra code --provider deepseek --model deepseek-v4-pro --deepseek-thinking enabled --deepseek-reasoning-effort high --deepseek-stream true -libra code --env-file .env.test --provider deepseek --model deepseek-v4-pro --deepseek-thinking enabled --deepseek-reasoning-effort high --deepseek-stream true - -# Kimi (Moonshot AI) -libra code --provider kimi -libra code --provider kimi --model kimi-k2.6 -libra code --provider kimi --model kimi-k2.6 --kimi-thinking disabled -libra code --provider kimi --model moonshot-v1-128k - -# Zhipu (GLM) -libra code --provider zhipu --model glm-5 - -# Ollama (local inference, no API key required, --model is required) -libra code --provider ollama --model llama3.2 -libra code --provider ollama --model codellama - -# Ollama with a remote instance -libra code --provider ollama --model llama3.2 --api-base http://remote-host:11434/v1 -libra code --provider ollama --model minimax-m2.7:cloud --api-base http://remote-host:11434/v1 --ollama-compact-tools - -# Ollama thinking control for reasoning models -OLLAMA_THINK=false libra code --provider ollama --model qwen3.6 -libra code --provider ollama --model qwen3.6 --ollama-thinking high -``` - -> **Note**: The `--api-base` CLI flag is only honored for the `ollama` provider. Other providers accept custom base URLs through their respective environment variables (e.g. `OPENAI_BASE_URL`). Use `--env-file .env.test` to load provider keys from a dotenv-style file and override stale shell environment variables. DeepSeek reasoning fields are opt-in with `--deepseek-thinking enabled|disabled` and `--deepseek-reasoning-effort low|medium|high|max`; `xhigh` is accepted as an alias for `max`. DeepSeek streaming is opt-in with `--deepseek-stream true`; `--stream` is accepted as a DeepSeek-only alias. Kimi thinking can be overridden with `--kimi-thinking enabled|disabled`; omit it to use the selected model's default. Ollama requests stream `/api/chat` responses by default, include a per-request `request_id` in debug logs, and default to `think:false` to keep tool calls responsive; use `--ollama-thinking auto|off|on|low|medium|high` for one run, or set `OLLAMA_THINK=true`, `low`, `medium`, `high`, or `auto` as the environment default. `auto` omits the `think` field and lets Ollama decide. Use `--ollama-compact-tools` or `OLLAMA_COMPACT_TOOLS=true` for remote/cloud Ollama endpoints that return 503s when receiving Libra's full tool schemas. - -| Provider | Default Model | Auth Env Variable | Base URL Override | Provider-specific Tuning | -|----------|--------------|-------------------|-------------------|-------------------------| -| `gemini` | `gemini-2.5-flash` | `GEMINI_API_KEY` | — | — | -| `openai` | `gpt-4o-mini` | `OPENAI_API_KEY` | `OPENAI_BASE_URL` | — | -| `anthropic` | `claude-sonnet-4-6` | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` | — | -| `deepseek` | `deepseek-chat` | `DEEPSEEK_API_KEY` | `--api-base` only (no env var) | `--deepseek-thinking`, `--deepseek-reasoning-effort`, `--deepseek-stream` | -| `kimi` | `kimi-k2.6` | `MOONSHOT_API_KEY` | `MOONSHOT_BASE_URL` | `--kimi-thinking` | -| `zhipu` | `glm-5` | `ZHIPU_API_KEY` | `ZHIPU_BASE_URL` | — | -| `ollama` | *(requires `--model`)* | `OLLAMA_API_KEY` for direct Cloud API | `OLLAMA_BASE_URL`, `--api-base` | `OLLAMA_THINK`, `OLLAMA_COMPACT_TOOLS`, `--ollama-thinking`, `--ollama-compact-tools` | - -`libra code` tries the Brave Search API for the `web_search` tool when `BRAVE_SEARCH_API_KEY` is set in the process environment or stored as `vault.env.BRAVE_SEARCH_API_KEY`; if Brave is not configured or the request fails, it falls back to DuckDuckGo HTML search. The session network policy must still allow outbound access. - --- -## AI-Native Extensions - -These subcommands are Libra-only (not present in Git) and form the AI-agent surface around the Git core. - -### `libra automation` — Rule-Based Automation - -Run scheduled (cron-driven) or ad-hoc automation rules. Rules live in repository config; the runner enforces a command safety preflight before any live shell action is spawned. History is persisted into the AI tables so a previous run can be replayed. - -```bash -libra automation list # List configured rules -libra automation run # Dry-run all due cron rules -libra automation run --rule my-rule # Force-run a single rule -libra automation run --now 2026-05-23T12:00:00Z # Simulate "now" when evaluating cron triggers -libra automation run --live # Actually spawn shell actions (subject to preflight) -libra automation history --limit 50 # Recent automation history -libra --json=pretty automation list # Structured JSON output for agents -``` - -### `libra agent` — External-Agent Capture +## Supported AI Providers -Capture sessions and checkpoints from external coding agents (Claude Code, Gemini, ...) into `refs/libra/traces`. Useful for replaying agent transcripts and pushing traces to a shared remote so the team can audit what an external agent actually did. +Libra already works with Claude Code, CodeX and OpenCode; support for other mainstream Agents will be released gradually. -```bash -libra agent status # Captured-session counts and recent checkpoints -libra agent enable --agent claude # Install hooks for one agent -libra agent enable # Enable every stable external agent -libra agent disable --agent claude -libra agent session list -libra agent checkpoint list -libra agent checkpoint show -libra agent checkpoint rewind # Replay as a JSONL transcript -libra agent clean [--all] # Drop temporary checkpoints from stopped sessions -libra agent doctor # Diagnose hook installation and capture state -libra agent push [--remote origin] # Push refs/libra/traces -libra agent rpc list # Discover libra-agent- RPC binaries on PATH -libra agent rpc invoke --params '{}' -``` - -### `libra publish` — Read-Only Cloudflare Worker Publishing - -Publish a snapshot of one or more refs to Cloudflare D1 (metadata) + R2 (objects) and serve them through a thin read-only Worker. Designed for sharing AI-generated artifacts or read-only mirrors of a repository. - -```bash -libra publish init --slug --clone-domain # Materialise the local Worker scaffold -libra publish status # Inspect local template / D1 ref drift -libra publish status --site-id -libra publish sync # Sync default refs to D1/R2 -libra publish sync --dry-run -libra publish sync --ref refs/heads/main -libra publish sync --force # Re-upload everything, ignoring CAS -libra publish sync --allow-sensitive-path # Override the deny list for a private site -libra publish deploy # Build and deploy the Worker -libra publish deploy --skip-deploy # Build only -libra publish unpublish --site-id --yes -``` - -### `libra sandbox` — AI Sandbox Diagnostics - -Inspect the command-safety sandbox used by AI tool execution: enforcement mode, network policy, seccomp/seatbelt status, and writable-root tmpdir layout. Every shell tool invoked by the AI runtime passes through this sandbox before it runs. - -```bash -libra sandbox status -libra sandbox inspect --command "" # Dry-run the safety classifier on a command -``` - -Relevant environment toggles: - -- `LIBRA_SANDBOX_ENFORCEMENT` — `disabled` / `warn` / `enforce` -- `LIBRA_SANDBOX_NETWORK_DISABLED` — block outbound network for sandboxed tools -- `LIBRA_LINUX_SANDBOX_EXE`, `LIBRA_USE_LINUX_SANDBOX_BWRAP` — Linux bwrap integration -- `LIBRA_SECCOMP_POLICY` — override the bundled `template/seccomp-default.json` allow-list - -### `libra code-control` and `libra graph` - -`code-control` drives an existing local `libra code` TUI from another process via a lease-based automation API — useful for AI-agent-in-the-loop scripts. `graph` opens a TUI for inspecting an AI thread's version graph. - -```bash -libra code-control --help -libra graph [--repo /path/to/repo] -``` - -### `libra usage` — AI Provider/Model Usage - -Report token usage and cost across providers and models, persisted by the AI runtime. - -```bash -libra usage # Summary across all providers -libra --json=pretty usage # Structured JSON output -``` +> See [docs.libra.tools](https://docs.libra.tools/en/docs/getting-started/agent) for provider setup and configuration details. --- -## Optional FUSE Backend - -Libra Code can use a FUSE overlay backend for temporary Agent task worktrees on -Unix platforms. This backend is optional: if FUSE is unavailable or fails its -health check, Libra logs a warning and falls back to the copy backend. - -### macOS - -Install [macFUSE](https://macfuse.github.io/) before using the FUSE backend. -The upstream project recommends downloading the latest installer from the -[macFUSE website or GitHub releases](https://github.com/macfuse/macfuse/wiki/Getting-Started). - -Homebrew can also install the cask for development machines: - -```bash -brew install --cask macfuse -``` - -Follow any macOS System Settings prompts to allow macFUSE if required by the -selected backend. After installation, verify that the mount helper expected by -Libra's FUSE library exists: - -```bash -test -x /Library/Filesystems/macfuse.fs/Contents/Resources/mount_macfuse -``` - -If Libra logs `macfuse mount binary not found`, macFUSE is not installed or the -mount helper is not present at the expected path. Install or repair macFUSE, then -start `libra code` again. - -### Linux - -Install FUSE 3 with your distribution package manager. Common package names are: - -```bash -# Debian / Ubuntu -sudo apt-get update -sudo apt-get install -y fuse3 - -# Fedora / RHEL -sudo dnf install fuse3 - -# Arch Linux -sudo pacman -S fuse3 -``` - -Verify that `fusermount3` is available: - -```bash -command -v fusermount3 -``` - -If the command is missing, Libra cannot use the unprivileged FUSE mount path and -will use the copy backend instead. +## Community & Resources +| Resource | Link | +|----------|------| +| **Website** | [libra.tools](https://www.libra.tools) | +| **Documentation** | [docs.libra.tools](https://docs.libra.tools) | +| **Discord** | [Join the community](https://discord.gg/MTbb5rDYsC) | +| **X / Twitter** | [@git_mono_AI](https://x.com/git_mono_AI) | --- -# Git-Compatible Features - -Libra's Git surface stays compatible enough to fetch from / push to standard Git servers (GitHub, Gitea, …). The per-command compatibility status (`supported` / `partial` / `unsupported` / `intentionally-different`) is tracked in [`COMPATIBILITY.md`](COMPATIBILITY.md). - -## Features - -### Clean Code +## Contributing -The codebase is designed to be clean and easy to read, making it maintainable and approachable for developers of all skill levels. - -### Cross-Platform - -- [x] Windows -- [x] Linux -- [x] macOS - -### Compatibility with Git - -Libra's core implementation is essentially compatible with **Git** (developed with reference to Git's own documentation), including support for on-disk formats such as: - -- `objects` -- `index` -- `pack` -- `pack-index` - -This allows Libra to interact seamlessly with Git servers (for example, `push` and `pull` work with standard Git remotes). - -### Differences from Git - -While maintaining compatibility with Git, Libra intentionally diverges in some areas: - -- Uses an **SQLite** database to manage loosely structured files such as `config`, `HEAD`, and `refs`, providing unified and transactional management instead of plain-text files. -- Records AI threads, runs, decisions, and patchset snapshots in the same SQLite database (see [AI Data Storage](#ai-data-storage)). -- Object storage can be tiered into S3/R2; backups go to Cloudflare D1/R2. - -## grep - -`grep` searches tracked working-tree files, the index (`--cached`), or committed trees (`--tree `) using regular expressions by default. It also supports fixed-string mode, multiple explicit patterns, pattern files, and requiring all patterns to match within the same file. - -```bash -# Search tracked working-tree files with a regex -libra grep "foo.*bar" - -# Search with multiple explicit patterns -libra grep -e alpha -e beta - -# Require every pattern to appear in the same file -libra grep --all-match -e alpha -e beta - -# Search the staged/index version of tracked files -libra grep --cached "needle" - -# Search a specific revision or branch -libra grep --tree HEAD "needle" -libra grep --tree main "needle" - -# Read patterns from a file -libra grep -f patterns.txt -``` - -## Bisect — Binary Search for Bugs - -Libra implements a `bisect` subcommand that uses binary search to find the commit that introduced a bug. It is broadly compatible with `git bisect`. - -### Basic Usage - -```bash -# Start a bisect session -libra bisect start - -# Mark the current commit as bad (contains the bug) -libra bisect bad - -# Mark a known-good commit -libra bisect good - -# After marking, bisect will checkout commits for you to test -# Continue marking commits as good/bad until the culprit is found - -# End the session and restore your original HEAD -libra bisect reset -``` - -### Quick Start with Known Bounds - -```bash -# Start with both bad and good commits specified -libra bisect start HEAD~10 HEAD~20 # HEAD~10 is bad, HEAD~20 is good -``` - -### Subcommands - -- `libra bisect start [ []]` – start a new bisect session -- `libra bisect bad []` – mark a commit as bad (contains the bug) -- `libra bisect good []` – mark a commit as good (bug-free) -- `libra bisect skip []` – skip the current commit (untestable) -- `libra bisect reset []` – end the session and restore original HEAD -- `libra bisect log` – show the current bisect state - -### Safety Features - -Libra's bisect implementation includes several safety guards: - -- **Clean working tree required**: Bisect will not start if you have uncommitted changes (including ignored files like `.env`) -- **Bare repository protection**: Bisect is blocked in bare repositories (no working tree) -- **State preserved until reset**: After finding the culprit, bisect state is preserved so you can run `bisect reset` to restore your original branch -- **Branch restoration**: `bisect reset` restores you to your original branch, not a detached HEAD - -## Worktree Management - -Libra implements a `worktree` subcommand that is broadly compatible with `git worktree`, allowing you to manage multiple working directories attached to the same repository storage. - -Unlike `git worktree remove`, Libra does **not** delete worktree directories on disk by default. - -Supported subcommands: - -- `libra worktree add ` – create a new linked working tree at `` -- `libra worktree list` – list all registered working trees (including the main worktree) -- `libra worktree lock [--reason ]` – mark a worktree as locked with an optional reason -- `libra worktree unlock ` – unlock a previously locked worktree -- `libra worktree move ` – move a worktree directory to a new location -- `libra worktree prune` – prune missing or non-existent worktrees from the registry -- `libra worktree remove ` – remove a worktree from the registry without deleting its directory on disk (the main worktree cannot be removed) -- `libra worktree umount [--cleanup]` – unmount a FUSE worktree or stale Agent task worktree mountpoint -- `libra worktree repair` – repair inconsistent worktree state if the registry and directories get out of sync - -## Vault-Backed Signing - -Libra supports repository-local vault initialization for commit signing: - -```bash -libra init [--separate-libra-dir ] [] -``` - -Vault is enabled by default for all `libra init` invocations — no extra flag is needed. - -When vault is enabled: - -- A vault database (`vault.db`) is created in the repository storage directory (`.libra/` or the directory passed via `--separate-libra-dir`). -- Libra generates a signing key and enables `vault.signing=true`. -- The vault unseal key is stored outside the repository at `~/.libra/vault-keys/`. -- The encrypted root token is stored in repository config (`vault.roottoken_enc`). - -Security note: - -- Libra no longer falls back to storing the unseal key inside repository config. -- If the home directory is not writable/usable, `libra init` fails with a fatal error. - -Troubleshooting: - -- Ensure `HOME` (or `USERPROFILE` on Windows) points to a writable directory. -- In container/CI environments, explicitly set `HOME` to a writable path before running `libra init`. - -Key management commands: - -```bash -# Print current signing GPG public key (for GitHub GPG key settings) -libra config get vault.gpg.pubkey - -# Generate a repo-local SSH key for a configured remote -libra config generate-ssh-key --remote origin - -# Print the SSH public key for a configured remote -libra config get vault.ssh.origin.pubkey - -# Generate (or rotate) vault GPG signing key and print public key -libra config generate-gpg-key [--name ] [--email ] -``` - -See `docs/commands/config.md` for the full `libra config` command reference and migration notes. - -### GitHub End-to-End Verification (libvault + Git conversion) - -The following flow validates: - -- `libvault` integration with Libra storage (`.libra/vault.db` + config metadata in SQLite) -- Conversion from Git repository format to Libra repository format -- Vault-backed GPG signing on commit -- SSH push from Libra to GitHub - -```bash -# 1) Clone an existing GitHub repository locally with Git (SSH). -# (This step can use your existing SSH credential.) -git clone git@github.com:/.git /tmp/-git - -# 2) Convert the cloned Git repository into a Libra repository and -# initialize vault in the same command. -mkdir -p /tmp/-libra -cd /tmp/-libra -libra init --from-git-repository /tmp/-git - -# 3) Export vault public keys and register them in GitHub settings: -# - GPG key: GitHub -> Settings -> SSH and GPG keys -> New GPG key -# - SSH key: GitHub -> Settings -> SSH and GPG keys -> New SSH key -libra config get vault.gpg.pubkey -libra config generate-ssh-key --remote origin -libra config get vault.ssh.origin.pubkey - -# 4) Make sure origin points to GitHub SSH URL in Libra config. -libra remote set-url origin git@github.com:/.git - -# 5) Create a signed commit and push through SSH. -echo "vault e2e" > vault-e2e.txt -libra add vault-e2e.txt -libra commit -m "feat(vault): verify signed commit to GitHub" -libra push origin master -``` - -Verification points: - -- `libra commit` should produce a commit object containing `gpgsig`. -- `libra push` should succeed over SSH (`git@github.com:...`). -- The commit should appear in GitHub with signature metadata. - -Note: - -- For the very first `git clone` in step 1, Git may still use your existing SSH credentials. - After step 3, Libra fetch/push uses the vault-generated key for this repository. - -## 🚧 Pending Git commands (not yet supported) - -The following Git top-level commands are currently **not implemented** in Libra (excluding `submodule` and `subtree`, which are intentionally omitted): - -- `gc` – garbage-collect unreachable objects and pack files -- `prune` – remove loose objects that are no longer reachable -- `pack-objects` / `unpack-objects` – pack and unpack object collections -- `remote show `-style detailed inspection – show detailed remote info -- `fetch-pack` / `push-pack` – low-level fetch/push operations -- `filter-branch` (or `git filter-repo`) – rewrite history - -These commands are slated for future implementation according to the project roadmap. (Several commands once listed here are now implemented — `maintenance`, `notes` (add/append/copy/edit/show/list/remove), and `archive` — and have moved out of this list.) The full per-command compatibility status (`supported` / `partial` / `unsupported` / `intentionally-different`) is tracked in [`COMPATIBILITY.md`](COMPATIBILITY.md). - -## Note on Submodule and Subtree - -Libra does **not** provide the `submodule` or `subtree` commands. Because Libra stores objects in an S3-compatible backend and is designed around a **Monorepo** layout with **Trunk-based Development**, the use-cases that `git submodule`/`git subtree` address (embedding separate repositories) are handled differently – large external data lives in S3 and all code lives in a single repository. - -This design choice simplifies dependency management and aligns with Libra's goal of supporting ultra-large repositories while keeping a single source of truth. - ---- - -## Error Reporting - -CLI failures use stable exit codes and stable error codes. When `stderr` is not a TTY, Libra also appends a JSON stderr report for agents and wrappers. Set `LIBRA_ERROR_JSON=1` to force that structured report in interactive terminals. -Run `libra help error-codes` for the built-in CLI reference. -See [docs/error-codes.md](docs/error-codes.md). - ---- - -## Contributing & Development - -Before submitting a Pull Request, please ensure your code passes the following checks: +We welcome contributions from developers, AI researchers, and anyone passionate about the future of software creation. Before submitting a Pull Request, please ensure your code passes our quality checks: ```bash # Run clippy with all warnings treated as errors @@ -640,57 +173,29 @@ cargo clippy --all-targets --all-features -- -D warnings # Check code formatting (requires nightly toolchain) cargo +nightly fmt --all --check -``` -Both commands must complete without any warnings. The clippy check treats all warnings as errors, and the formatter check ensures code follows the project style guide. - -If the formatting check fails, you can automatically fix formatting issues by running: - -```bash +# Fix formatting automatically if needed cargo +nightly fmt --all ``` -## Run on Windows +For Windows builds, please see the [Windows build guide](docs/installation/windows.md) for OpenSSL setup instructions. -If you are building Libra on Windows for the first time, install OpenSSL before running -`cargo build` or `cargo test`. The easiest setup is to use a precompiled OpenSSL package: - +For detailed contribution guidelines, see [docs/development/contributing.md](docs/development/contributing.md). -Recommended setup: +--- -1. Install a 64-bit OpenSSL build that matches the default Rust Windows target - `x86_64-pc-windows-msvc`. -2. Note the installation directory, for example `D:\OpenSSL-Win64`. -3. Create `.cargo/config.toml` in the project root if it does not already exist. -4. Add OpenSSL environment overrides so Cargo and dependent build scripts can find the - headers and libraries. +## License -Project layout: +MIT License — see [LICENSE](LICENSE) for details. -```text -.cargo/ - config.toml -``` +Copyright (c) 2025-2026 Web3 Infrastructure Foundation. -Example `.cargo/config.toml`: +Copyright (c) 2026 GitMono Limited. -```toml -[env] -OPENSSL_DIR = "D:\\OpenSSL-Win64" -OPENSSL_LIB_DIR = "D:\\OpenSSL-Win64\\lib\\VC\\static" -OPENSSL_INCLUDE_DIR = "D:\\OpenSSL-Win64\\include" -OPENSSL_NO_VENDOR = "1" -``` +--- -Notes: +
-- Update the paths if OpenSSL is installed in a different directory. -- If `.cargo/config.toml` already exists, merge these entries instead of replacing the file. -- Some OpenSSL installers place libraries in a different subdirectory. If `VC\\static` does - not exist in your installation, point `OPENSSL_LIB_DIR` at the directory that contains the - `.lib` files for your installation. -- After updating the config, open a new terminal and verify the setup with: +**[Get Started](https://docs.libra.tools/en/docs/getting-started) · [Join Discord](https://discord.gg/MTbb5rDYsC) · [Follow on X](https://x.com/git_mono_AI)** -```bash -cargo build -``` +
diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 000000000..a4f847bf9 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,201 @@ +[English](README.md) | 中文 + +![Libra](docs/image/libra-banner.png) + +
+ +# Libra — 面向 AI Agent 的 AI 原生扩展版本控制系统 + +**版本化整个软件创造生命周期，而非仅仅是代码。** + +
+ +Libra 是一个 AI 原生基础设施，捕获并结构化软件开发的完整生命周期，记录从人类意图、AI 推理到验证和发布的每一个步骤。 + +我们的使命是确保每一次软件创造都成为持久的知识，而非被丢弃的工作流数据，赋能开发者、团队和 AI 系统去检索、复用并基于每一份软件背后的智能进行构建。 + +当 AI 成为软件的主要生产者时，Libra 提供基础架构来保存、累积并释放软件创造的长期价值。 + +
+ +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![CI](https://github.com/wingwangsz/libra/actions/workflows/base.yml/badge.svg)](https://github.com/wingwangsz/libra/actions/workflows/base.yml) +[![Discord](https://img.shields.io/badge/Discord-加入社区-%235865F2?logo=discord&logoColor=white)](https://discord.gg/MTbb5rDYsC) +[![X](https://img.shields.io/badge/X-%40git_mono_AI-%231DA1F2?logo=x&logoColor=white)](https://x.com/git_mono_AI) +[![文档](https://img.shields.io/badge/文档-docs.libra.tools-29B1FF)](https://docs.libra.tools) + +
+ +--- + +## 核心差异 + +| 能力 | 传统版本控制（Git） | Libra | +|-----------|----------------------|-------| +| **版本化内容** | 仅源代码 | 代码 + AI 推理 + 决策 + 验证报告 + 会话记录 | +| **AI 协作** | 手动提交信息 | 原生 AI Agent 线程，完整审计追踪 | +| **知识复用** | 代码快照 | 跨项目可复用的智能资产 | +| **安全** | 外部 GPG/SSH 配置 | 内置 Vault，每个仓库独立隔离密钥 | +| **供应商锁定** | 不适用 | 7+ 家 AI 提供商，自由切换 | +| **自动化** | 外部 CI/CD | 内置 Cron 驱动的 Agent 自动化 | + +--- + +## 快速开始 + +### 安装 + +```bash +# macOS / Linux（推荐） +curl -fsSL https://download.libra.tools/install.sh | sh + +# Homebrew（macOS） +brew install libra + +# 从源码编译（需要 Rust） +git clone https://github.com/wingwangsz/libra.git +cd libra +cargo build --release +``` + +### 初始化你的第一个仓库 + +```bash +# 创建新的 Libra 仓库 +libra init my-project +cd my-project + +# 或从现有 Git 仓库转换 +libra init --from-git-repository /path/to/existing/git/repo +``` + +### 使用 Agent 捕获 + +```bash +# 为你的 Agent 启用捕获钩子（以 codex 为例） +libra agent enable + +# 正常使用你的 Agent 工具——Libra 会自动捕获会话和检查点 +codex + +# 查看已捕获的会话 +libra agent session list +libra agent checkpoint list +``` + +> 查看 [Agent 捕获文档](https://docs.libra.tools/en/docs/getting-started/agent)了解所有支持的 Agent、高级配置和会话管理。 + +--- + +## 核心特性 + +### 🧠 AI 原生线程与持久化 + +每一个 AI Agent 会话都是 Libra 中的一等公民。线程、计划、任务、决策、验证报告、工具调用和代码补丁快照都直接持久化在仓库中，与代码共存。没有外部状态——一切都是可持久化、可查询、可回放的。 + +``` +.libra/ +├── libra.db # SQLite：Git 核心 + AI 线程 + 运行时合约 +├── vault.db # 加密密钥库（提供商密钥、签名密钥） +├── objects/ # 对象存储（loose + pack，与 Git 兼容） +├── sessions/ # AI 会话记录（JSONL 格式） +└── ai/ # AI 运行时工作文件 +``` + +### 🔄 Git 兼容基础 + +Libra 使用 Git 的语言。磁盘格式（objects、index、pack、pack-index）和传输协议与标准 Git 服务器（GitHub、GitLab、Gitea 等）完全兼容。你可以零摩擦地向任何 Git 远程仓库 `push` 和 `pull`。 + +关键区别：Git 管理文件。Libra 管理**创造**。 + +### 🔐 Vault 安全 + +每次 `libra init` 自动创建仓库级加密密钥管理： +- **GPG 签名密钥**用于提交验证 +- **SSH 密钥**用于远程认证 +- **AI 提供商凭证**安全存储 + +无需外部密钥管理配置。每个仓库的密钥独立隔离，永不离库。 + +### 🛡️ 命令安全沙箱 + +每个 AI Agent 的工具调用都经过可配置的安全沙箱，包含命令预检、网络策略执行和可选的 seccomp/seatbelt 限制。定义 Agent 能做什么、不能做什么。 + +### ☁️ 分层云存储与备份 + +- **分层存储**：将大对象卸载到 S3/R2/RustFS，本地 LRU 缓存 +- **云端备份**：将完整仓库状态（含 AI 历史）同步到 Cloudflare D1 + R2 +- **可移植**：在不同机器之间迁移 Libra 仓库，AI 上下文完整保留 + +### 🌐 原生 MCP 协议支持 + +Libra 原生支持 [Model Context Protocol](https://modelcontextprotocol.io/)，可直接与 Claude Desktop、Cursor 和任何 MCP 兼容客户端集成。配置一次，到处使用。 + +```json +{ + "mcpServers": { + "libra": { + "command": "/path/to/libra", + "args": ["code", "--stdio"], + "cwd": "/path/to/your/libra/repo" + } + } +} +``` + +--- + +## 支持的 AI 提供商 + +Libra 目前已支持 Claude Code、CodeX 和 OpenCode；对其他主流 Agent 的支持将陆续发布。 + +> 前往 [docs.libra.tools](https://docs.libra.tools/en/docs/getting-started/agent) 查看提供商配置详情。 + +--- + +## 社区与资源 + +| 资源 | 链接 | +|----------|------| +| **官网** | [libra.tools](https://www.libra.tools) | +| **文档** | [docs.libra.tools](https://docs.libra.tools) | +| **Discord** | [加入社区](https://discord.gg/MTbb5rDYsC) | +| **X / Twitter** | [@git_mono_AI](https://x.com/git_mono_AI) | +--- + +## 贡献指南 + +我们欢迎来自开发者、AI 研究人员和所有热爱软件创造未来的人的贡献。在提交 Pull Request 之前，请确保你的代码通过我们的质量检查： + +```bash +# 运行 clippy，所有警告视为错误 +cargo clippy --all-targets --all-features -- -D warnings + +# 检查代码格式（需要 nightly 工具链） +cargo +nightly fmt --all --check + +# 如需要自动修复格式 +cargo +nightly fmt --all +``` + +Windows 构建用户请查看 [Windows 构建指南](docs/installation/windows.md) 了解 OpenSSL 配置。 + +详细贡献指南请参见 [docs/development/contributing.md](docs/development/contributing.md)。 + +--- + +## 许可证 + +MIT 许可证 — 详情见 [LICENSE](LICENSE)。 + +Copyright (c) 2025-2026 Web3 Infrastructure Foundation. + +Copyright (c) 2026 GitMono Limited. + +--- + +
+ +**[开始使用](https://docs.libra.tools/en/docs/getting-started) · [加入 Discord](https://discord.gg/MTbb5rDYsC) · [关注 X](https://x.com/git_mono_AI)** + +
diff --git a/docs/image/libra-banner.png b/docs/image/libra-banner.png new file mode 100644 index 000000000..ed2c70099 Binary files /dev/null and b/docs/image/libra-banner.png differ diff --git a/docs/image/libra-demo.png b/docs/image/libra-demo.png new file mode 100644 index 000000000..d5275fa28 Binary files /dev/null and b/docs/image/libra-demo.png differ diff --git a/docs/image/libra-logo.svg b/docs/image/libra-logo.svg new file mode 100644 index 000000000..e65dfa5bd --- /dev/null +++ b/docs/image/libra-logo.svg @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + +