Skip to content

An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.

Rust

omx(team): auto-checkpoint worker-4 [unknown]

bellman2db0a5f70d3e
diff --git a/.github/scripts/check_release_readiness.py b/.github/scripts/check_release_readiness.py
new file mode 100644
index 00000000..d356abb2
--- /dev/null
+++ b/.github/scripts/check_release_readiness.py
@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Validate release-readiness docs that are easy to regress.
+
+The check is intentionally dependency-free so it can run on developer machines,
+Windows CI, and minimal release jobs. It validates:
+
+* required repository policy files exist;
+* local Markdown links and image targets resolve;
+* local heading anchors referenced from Markdown resolve; and
+* command examples do not present the deprecated `cargo install claw-code`
+ package as an executable install path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+import re
+import sys
+
+ROOT = Path(__file__).resolve().parents[2]
+
+REQUIRED_POLICY_FILES = [
+ "LICENSE",
+ "CONTRIBUTING.md",
+ "SECURITY.md",
+ "SUPPORT.md",
+ "CODE_OF_CONDUCT.md",
+]
+
+MARKDOWN_ROOTS = [
+ ROOT / "README.md",
+ ROOT / "USAGE.md",
+ ROOT / "PARITY.md",
+ ROOT / "PHILOSOPHY.md",
+ ROOT / "ROADMAP.md",
+ ROOT / "CONTRIBUTING.md",
+ ROOT / "SECURITY.md",
+ ROOT / "SUPPORT.md",
+ ROOT / "CODE_OF_CONDUCT.md",
+ ROOT / "docs",
+ ROOT / "rust" / "README.md",
+ ROOT / "rust" / "USAGE.md",
+ ROOT / "rust" / "MOCK_PARITY_HARNESS.md",
+]
+
+LINK_PATTERN = re.compile(r"(?<!!)\[[^\]\n]+\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
+HTML_LINK_PATTERN = re.compile(r"""<(?:a|img)\b[^>]*(?:href|src)=["']([^"']+)["']""", re.I)
+FENCE_PATTERN = re.compile(r"```(?P<lang>[^\n`]*)\n(?P<body>.*?)```", re.S)
+
+
+def iter_markdown_files() -> list[Path]:
+ files: set[Path] = set()
+ for entry in MARKDOWN_ROOTS:
+ if entry.is_file():
+ files.add(entry)
+ elif entry.is_dir():
+ files.update(entry.rglob("*.md"))
+ return sorted(files)
+
+
+def github_anchor(heading: str) -> str:
+ anchor = heading.strip().lower()
+ anchor = re.sub(r"<[^>]+>", "", anchor)
+ anchor = re.sub(r"`([^`]*)`", r"\1", anchor)
+ anchor = re.sub(r"[^a-z0-9 _-]", "", anchor)
+ anchor = anchor.replace(" ", "-")
+ anchor = re.sub(r"-+", "-", anchor)
+ return anchor.strip("-")
+
+
+def anchors_for(path: Path) -> set[str]:
+ anchors: set[str] = set()
+ for line in path.read_text(encoding="utf-8").splitlines():
+ match = re.match(r"^(#{1,6})\s+(.+?)\s*#*\s*$", line)
+ if match:
+ anchors.add(github_anchor(match.group(2)))
+ return anchors
+
+
+def is_external(target: str) -> bool:
+ parsed = urlparse(target)
+ return parsed.scheme in {"http", "https", "mailto"}
+
+
+def validate_policies(errors: list[str]) -> None:
+ for relative in REQUIRED_POLICY_FILES:
+ path = ROOT / relative
+ if not path.is_file():
+ errors.append(f"missing required policy file: {relative}")
+
+
+def validate_markdown_links(errors: list[str]) -> None:
+ anchor_cache: dict[Path, set[str]] = {}
+ for path in iter_markdown_files():
+ text = path.read_text(encoding="utf-8")
+ candidates = [m.group(1) for m in LINK_PATTERN.finditer(text)]
+ candidates.extend(m.group(1) for m in HTML_LINK_PATTERN.finditer(text))
+ for target in candidates:
+ if (
+ not target
+ or is_external(target)
+ or target.startswith(("mailto:", "tel:", "data:"))
+ ):
+ continue
+ link_path, _, raw_anchor = target.partition("#")
+ if not link_path:
+ destination = path
+ else:
+ destination = (path.parent / unquote(link_path)).resolve()
+ try:
+ destination.relative_to(ROOT)
+ except ValueError:
+ errors.append(
+ f"{path.relative_to(ROOT)}: link escapes repo root: {target}"
+ )
+ continue
+ if not destination.exists():
+ errors.append(
+ f"{path.relative_to(ROOT)}: missing local link target: {target}"
+ )
+ continue
+ if raw_anchor and destination.suffix.lower() == ".md":
+ anchor = unquote(raw_anchor).lower()
+ anchor_cache.setdefault(destination, anchors_for(destination))
+ if anchor not in anchor_cache[destination]:
+ errors.append(
+ f"{path.relative_to(ROOT)}: missing anchor `{raw_anchor}` in "
+ f"{destination.relative_to(ROOT)}"
+ )
+
+
+def validate_command_examples(errors: list[str]) -> None:
+ for path in iter_markdown_files():
+ text = path.read_text(encoding="utf-8")
+ for match in FENCE_PATTERN.finditer(text):
+ lang = match.group("lang").strip().lower()
+ if lang not in {"bash", "sh", "shell", "zsh", "powershell", "ps1"}:
+ continue
+ body = match.group("body")
+ for offset, line in enumerate(body.splitlines(), start=1):
+ stripped = line.strip()
+ if not stripped or stripped.startswith(("#", ">")):
+ continue
+ if re.search(r"\bcargo\s+install\s+claw-code\b", stripped):
+ line_no = text.count("\n", 0, match.start()) + offset + 1
+ errors.append(
+ f"{path.relative_to(ROOT)}:{line_no}: deprecated "
+ "`cargo install claw-code` appears in an executable "
+ "command block; use build-from-source docs instead"
+ )
+
+
+def main() -> int:
+ errors: list[str] = []
+ validate_policies(errors)
+ validate_markdown_links(errors)
+ validate_command_examples(errors)
+ if errors:
+ print("release-readiness check failed:", file=sys.stderr)
+ for error in errors:
+ print(f" - {error}", file=sys.stderr)
+ return 1
+ print("release-readiness check passed")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 00000000..f9b4e0f9
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,32 @@
+# Code of Conduct
+
+## Our pledge
+
+We aim to make Claw Code a practical, respectful, and evidence-oriented
+community. Contributors and maintainers are expected to communicate with
+patience, assume good intent, and focus critique on the work rather than the
+person.
+
+## Expected behavior
+
+- Be respectful and direct.
+- Welcome newcomers and explain project-specific context when it matters.
+- Give actionable feedback with evidence, commands, logs, or links.
+- Respect privacy and do not pressure others to disclose credentials, private
+ prompts, employer information, or personal details.
+
+## Unacceptable behavior
+
+- Harassment, threats, insults, or discriminatory language.
+- Publishing another person's private information without permission.
+- Sharing secrets, exploit payloads, or private vulnerability details in public
+ channels.
+- Repeated off-topic disruption after maintainers ask for a thread to stop or
+ move.
+
+## Enforcement
+
+Maintainers may remove comments, close threads, restrict participation, or ban
+accounts that violate this code of conduct. Report concerns through the support
+or security paths described in [SUPPORT.md](./SUPPORT.md) and
+[SECURITY.md](./SECURITY.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..92c629ae
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,66 @@
+# Contributing to Claw Code
+
+Thanks for helping improve Claw Code. This repository is a Rust-first CLI
+workspace with supporting docs and compatibility fixtures.
+
+## Ground rules
+
+- Keep changes small, reviewable, and tied to a concrete issue or behavior.
+- Do not commit secrets, API keys, session transcripts with credentials, or
+ generated build output.
+- Prefer existing crate boundaries and utilities before adding dependencies.
+- Update documentation when a user-facing command, config key, or provider
+ behavior changes.
+- Keep examples copy/paste safe. Use placeholder keys such as `sk-ant-...` and
+ avoid commands that require live credentials unless the text explicitly says
+ so.
+
+## Local setup
+
+```bash
+git clone https://github.com/ultraworkers/claw-code
+cd claw-code/rust
+cargo build --workspace
+cargo test --workspace
+```
+
+On Windows PowerShell, build from the same `rust` workspace and run the binary
+with the `.exe` suffix:
+
+```powershell
+cd claw-code\rust
+cargo build --workspace
+.\target\debug\claw.exe --help
+```
+
+## Checks before opening a pull request
+
+Run the smallest relevant tests for your change, then the broader checks when
+you touch shared runtime, CLI, or docs surfaces:
+
+```bash
+cd rust
+cargo fmt --all --check
+cargo test --workspace
+cargo clippy --workspace
+```
+
+For documentation and release-readiness changes, also run:
+
+```bash
+python .github/scripts/check_doc_source_of_truth.py
+python .github/scripts/check_release_readiness.py
+```
+
+## Pull request guidance
+
+- Describe the user-visible reason for the change.
+- List the commands you ran and any known gaps.
+- Call out compatibility risks for CLI output, JSON schemas, plugin contracts,
+ provider behavior, or Windows/PowerShell examples.
+- Keep unrelated cleanup out of feature or fix pull requests.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](./LICENSE).
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 00000000..28e6960d
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UltraWorkers and Claw Code contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 00000000..282f6887
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,49 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes target the current `main` branch and the latest published
+release artifacts when available. Older experimental branches are not supported
+unless a maintainer explicitly marks them as supported.
+
+## Reporting a vulnerability
+
+Please do **not** open a public issue for a suspected vulnerability. Use GitHub
+private vulnerability reporting for `ultraworkers/claw-code` when available, or
+contact a maintainer through the repository's published support channel with a
+minimal, non-destructive reproduction.
+
+Include:
+
+- affected command, crate, or workflow;
+- operating system and shell, especially for Windows/PowerShell path issues;
+- whether live credentials, MCP servers, plugins, or workspace filesystem
+ access are involved;
+- expected impact and any safe proof-of-concept steps.
+
+Do not include real API keys, private prompts, session transcripts with secrets,
+or exploit payloads that modify third-party systems.
+
+## Scope
+
+In scope:
+
+- workspace path traversal or symlink escapes;
+- permission bypasses, sandbox misreporting, or unsafe tool execution;
+- credential disclosure in logs, JSON output, telemetry, docs, or examples;
+- plugin, hook, MCP, provider, or config behavior that can unexpectedly execute
+ code or leak secrets.
+
+Out of scope:
+
+- social engineering;
+- denial-of-service without a practical security impact;
+- issues that require already-compromised local developer credentials;
+- reports against third-party providers or upstream tools without a Claw Code
+ integration issue.
+
+## Handling expectations
+
+Maintainers will acknowledge valid private reports as soon as practical, keep
+discussion private until a fix or mitigation is available, and credit reporters
+when requested and appropriate.
diff --git a/SUPPORT.md b/SUPPORT.md
new file mode 100644
index 00000000..617eea0d
--- /dev/null
+++ b/SUPPORT.md
@@ -0,0 +1,24 @@
+# Support
+
+Use the lightest support path that fits the request:
+
+- **Usage questions:** start with [USAGE.md](./USAGE.md) and
+ [rust/README.md](./rust/README.md).
+- **Bugs or regressions:** open a GitHub issue with the command, OS/shell,
+ expected behavior, actual behavior, and relevant non-secret output.
+- **Security issues:** follow [SECURITY.md](./SECURITY.md) instead of opening a
+ public issue.
+- **Community discussion:** use the UltraWorkers Discord linked from
+ [README.md](./README.md).
+
+When asking for help, include:
+
+```text
+claw --version
+claw doctor
+operating system and shell
+command you ran
+```
+
+Redact API keys, bearer tokens, private prompts, session transcripts, and local
+paths that reveal sensitive information before sharing output.