{"id":49281797,"url":"https://github.com/configflux/weld","last_synced_at":"2026-05-02T20:01:13.594Z","repository":{"id":351159353,"uuid":"1207935049","full_name":"configflux/weld","owner":"configflux","description":"Weld connected structure toolkit for agent-first repository discovery","archived":false,"fork":false,"pushed_at":"2026-04-25T18:41:13.000Z","size":1512,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T19:25:06.290Z","etag":null,"topics":["ai-agents","ast","claude-code","code-intelligence","codebase-analysis","developer-tools","knowledge-graph","llm-tools","mcp","mcp-server","model-context-protocol","python","static-analysis","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/configflux.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T15:49:20.000Z","updated_at":"2026-04-25T18:38:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/configflux/weld","commit_stats":null,"previous_names":["configflux/cortex","configflux/weld"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/configflux/weld","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/configflux%2Fweld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/configflux%2Fweld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/configflux%2Fweld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/configflux%2Fweld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/configflux","download_url":"https://codeload.github.com/configflux/weld/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/configflux%2Fweld/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32547651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T19:18:06.202Z","status":"ssl_error","status_checked_at":"2026-05-02T19:16:21.335Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ast","claude-code","code-intelligence","codebase-analysis","developer-tools","knowledge-graph","llm-tools","mcp","mcp-server","model-context-protocol","python","static-analysis","tree-sitter"],"created_at":"2026-04-25T19:01:10.077Z","updated_at":"2026-05-02T20:01:13.582Z","avatar_url":"https://github.com/configflux.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Weld\n\n\u003c!-- markdownlint-disable-next-line MD013 --\u003e\n[![CI](https://github.com/configflux/weld/actions/workflows/ci.yml/badge.svg)](https://github.com/configflux/weld/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/configflux-weld.svg)](https://pypi.org/project/configflux-weld/) [![Python versions](https://img.shields.io/pypi/pyversions/configflux-weld.svg)](https://pypi.org/project/configflux-weld/) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\nA local codebase graph for AI coding agents. Weld scans code, docs, CI, build\nfiles, runtime configs, and repo boundaries into a deterministic graph. Agents\ncan query this graph through CLI or MCP instead of rediscovering the repository\nfrom scratch every session.\n\nThe graph lives on disk (`.weld/graph.json`), stays under your control, and\nanswers the questions agents and humans repeatedly ask about a codebase: where\na capability lives, which docs are authoritative, what build and test surfaces\na change touches, and what boundaries constrain the implementation.\n\n\u003c!-- evaluator-note: latest=v0.15.0 --\u003e\n\u003e **Evaluators: start with v0.14.0.** v0.14.0 lands deterministic\n\u003e multi-language graph closure, two new discovery strategies\n\u003e (`concept_from_bd`, `test_peer`), module-level Python constants in\n\u003e `wd find` and `wd query`, and a `copilot-cli` probe in `wd doctor`,\n\u003e on top of the v0.13.2 opt-in gitignore-aware workspace scans, the\n\u003e v0.13.1 C# / C++ startup entrypoint modeling, and the v0.13.0 trace\n\u003e import contract. It is the recommended starting point for\n\u003e cross-language startup modeling, polyrepo workspace bootstrapping,\n\u003e agent graph visualization, local-only telemetry, and the `copilot-cli`\n\u003e enrichment provider. See the [`CHANGELOG.md`](CHANGELOG.md) entries\n\u003e for v0.14.0, v0.13.2, and v0.13.1 for details.\n\n**Try it in 5 minutes →** [docs/tutorial-5-minutes.md](docs/tutorial-5-minutes.md)\nwalks through `wd init`, `discover`, `brief`, `query`, `context`, and `path`\nagainst demo workspaces. Spin up a clean demo with one command:\n\n```bash\nscripts/create-polyrepo-demo.sh /tmp/weld-polyrepo-demo\n# or\nscripts/create-monorepo-demo.sh /tmp/weld-monorepo-demo\n```\n\nEach script materializes a self-contained demo directory with seeded source\nfiles, `.weld` configs, and committed git history -- ready for `wd discover`.\nIf you have Weld installed but no source checkout, the same demos are\navailable through the CLI: `wd demo list`, `wd demo monorepo --init \u003cdir\u003e`,\n`wd demo polyrepo --init \u003cdir\u003e`.\n\n## Use Weld when…\n\n- your repo is too large for an agent to understand in one pass\n- your system spans multiple repositories\n- architecture is spread across code, docs, CI, configs, and service contracts\n- you want reproducible repo context instead of ad-hoc chat memory\n\n## When not to use Weld\n\n- **Your repo is small (under ~50 files).** An agent can read it end-to-end;\n  a graph adds overhead without payoff.\n- **`grep` plus your IDE already answers your questions.** If nothing is\n  missing from that workflow, Weld has nothing to add.\n- **You only need symbol navigation.** Go-to-definition and find-references\n  are an LSP job. Weld covers architecture, contracts, docs, and CI -- not\n  IDE jump-to.\n- **You expect compiler-grade static analysis.** Weld is a pragmatic graph,\n  not a type checker or dataflow engine. It will not catch every reference\n  or prove correctness.\n- **You do not want repo-local configuration.** Weld writes config to\n  `.weld/` (`discover.yaml`, `workspaces.yaml`, `strategies/`) and\n  expects that **config** to be committed alongside your code. Generated\n  graphs (`graph.json`, `agent-graph.json`) are gitignored by default;\n  the opt-in `wd init --track-graphs` team workflow commits them for\n  warm-CI / warm-MCP setups instead. If even committing config is\n  unacceptable, Weld is the wrong tool.\n\n## How Weld compares\n\nWeld is not a replacement for the tools below -- it sits alongside them and\ngives agents a persistent, queryable map of the repository. Each of these\ntools is excellent at what it does; Weld adds the connected structure they\nwere not designed to provide.\n\n| Tool | Gives you | Weld adds |\n|---|---|---|\n| grep / ripgrep | Fast literal and regex search over file contents. | Typed nodes and edges -- a symbol, route, doc, or config is an addressable entity with neighbours, not a line of text. |\n| ctags / LSP | Symbol navigation and go-to-definition inside one language. | A cross-language graph that also covers docs, CI, configs, service contracts, and repo boundaries -- surfaces an IDE was never meant to index. |\n| Sourcegraph | Hosted code search and references across large fleets of repos. | A local, repo-local graph that lives next to your code. By default Weld tracks only config and lets you opt in (`wd init --track-graphs`) to commit the generated graph for warm-CI / warm-MCP setups. No server, no indexing fleet; agents query it offline through CLI or MCP. |\n| vector DB / RAG | Embedding-based semantic recall over chunks of text. | Deterministic structure. Query results are exact nodes and edges with provenance, not top-k fuzzy matches, so agents can follow relationships instead of guessing. |\n| Copilot / Claude Code / OpenCode | In-editor and agentic code generation and chat. | Shared repo context those agents can read through MCP -- the same graph across sessions and tools, instead of each agent rediscovering the repo on every run. |\n\n## Key features\n\n- **Whole-codebase discovery** — not just source code. Covers docs, config,\n  CI workflows, infrastructure, and build files.\n- **Startup and runtime flow** — models common Python, C#/.NET, and C++ entrypoints\n  and connects them to services, boundaries, and deploy/runtime surfaces.\n- **Config-driven** — point `.weld/discover.yaml` at your repo and tune\n  what gets extracted.\n- **Multi-language** — bundled tree-sitter strategies for Python, TypeScript/JS,\n  Go, Rust, C#, C++, Java, and ROS2.\n- **Plugin architecture** — drop a `.py` file in `.weld/strategies/` to\n  extract anything repo-specific.\n- **Agent Graph** — discover agents, skills, prompts, commands, hooks,\n  instructions, MCP servers, and platform-specific copies into\n  `.weld/agent-graph.json`; see the\n  [Agent Graph guide](docs/agent-graph.md) for node and edge types,\n  authority/drift, and limitations, and the\n  [platform support matrix](docs/platform-support.md) for tested surfaces.\n- **Agent-native** — generates MCP config snippets by default and ships an\n  optional stdio MCP server so Claude Code, Codex, and other agents can query\n  the graph directly.\n- **Zero external dependencies** — runs from a plain checkout with Python \u003e= 3.10.\n  Tree-sitter is optional.\n\n## Quickstart\n\n```bash\n# Install (recommended — see the Install section for alternatives)\nuv tool install configflux-weld\n\n# Bootstrap config for your repo\nwd init\n\n# Run discovery and save the graph (safe mode by default — see Trust model below)\nwd discover --safe --output .weld/graph.json\n\n# Query the graph\nwd query \"authentication\"\nwd trace \"how does this service start\"\nwd find \"login\"\nwd context file:src/auth/handler\nwd viz --no-open\nwd stale\n```\n\nDrop `--safe` once you trust the repository's project-local strategies and\nexternal-JSON adapters; the [Trust model](#trust-model) section below explains\nwhat `--safe` disables and when it is appropriate to remove.\n\nTry it on a real example:\n[examples/04-monorepo-typescript](examples/04-monorepo-typescript/) (monorepo) ·\n[examples/05-polyrepo](examples/05-polyrepo/) (polyrepo federation).\n\nSample output (`wd query \"auth\"` — default human form, trimmed):\n\n```text\n# query: auth\n  matches (1):\n    1. symbol:src/auth/handler.py:authenticate  [type: function]\n       label: authenticate\n       description: Validate a bearer token and return the caller identity.\n  neighbors (1):\n    - route:/login  [type: route]\n```\n\nAll `wd` retrieval commands default to human-readable text and accept\n`--json` for the stable JSON envelope (ADR 0040). Pass `--json` when\npiping to `jq` or other scripted consumers — the schema is unchanged\nfrom the previous release. Sample `wd query \"auth\" --json`:\n\n```json\n{\n  \"query\": \"auth\",\n  \"matches\": [\n    {\n      \"id\": \"symbol:src/auth/handler.py:authenticate\",\n      \"label\": \"authenticate\",\n      \"type\": \"function\",\n      \"props\": {\n        \"file\": \"src/auth/handler.py\",\n        \"exports\": [\"authenticate\"],\n        \"description\": \"Validate a bearer token and return the caller identity.\"\n      }\n    }\n  ],\n  \"neighbors\": [{\"id\": \"route:/login\", \"type\": \"route\"}],\n  \"edges\": [\n    {\"from\": \"route:/login\", \"to\": \"symbol:src/auth/handler.py:authenticate\", \"type\": \"calls\"}\n  ]\n}\n```\n\nSee [Install](#install) for alternatives (local checkout, pip, raw source).\n\n### Agent Graph for AI customizations\n\nWeld also maps the AI customization layer around a repository: agents, skills,\ninstructions, prompts, commands, hooks, MCP servers, tool permissions, and\nplatform variants. The Agent Graph is static and repo-bound; discovery reads\nknown customization files and does not execute project code.\n\n```bash\nwd agents discover\nwd agents list\nwd agents audit\nwd agents explain planner\nwd agents impact .github/agents/planner.agent.md\nwd agents plan-change \"planner should always include test strategy\"\nwd agents viz --no-open\n```\n\nUse `--json` on `list`, `explain`, `impact`, `audit`, and `plan-change` for\nagent-friendly output. Use `wd agents rediscover` when you want an explicit\nrefresh of `.weld/agent-graph.json` before inspecting the persisted graph.\nUse `wd agents viz` after discovery to open a local read-only browser explorer\nfor the persisted Agent Graph.\nStatic discovery and configuration generation are available for several\nagent platforms; runtime validation is tracked per client in the\n[platform support matrix](docs/platform-support.md). The\n[Agent Graph guide](docs/agent-graph.md) documents node and edge types,\nauthority and drift, and the read-only-first policy.\n\n### Agent-first onboarding\n\nIf an agent or coding assistant is driving setup, use the short bootstrap\npath:\n\n```bash\nuv tool install configflux-weld   # recommended — see Install for alternatives\nwd prime                  # show setup status + per-framework surface matrix\nwd bootstrap claude       # writes .claude/commands/weld.md\nwd bootstrap codex        # writes .codex/skills/weld/SKILL.md + .codex/config.toml\nwd bootstrap copilot      # writes .github/skills/weld/SKILL.md + .github/instructions/weld.instructions.md\n```\n\nAll three `wd bootstrap` frameworks accept opt-out flags:\n\n- `--no-mcp` — skip the MCP pair (`.codex/config.toml` for codex; the `.mcp.json` guidance block for copilot/claude).\n- `--no-enrich` — write the `.cli.md` variant that omits `wd enrich`.\n- `--cli-only` — shorthand for `--no-mcp --no-enrich`.\n\nTo upgrade existing bootstrap files after pulling a new weld release, use\nthe diff-aware upgrade path:\n\n- `wd bootstrap \u003cframework\u003e --diff` — print unified diffs between bundled\n  templates and your on-disk copies without writing. Exits 1 when any\n  file differs, 0 otherwise, so it composes with CI checks.\n- `wd bootstrap \u003cframework\u003e --force` — overwrite targeted files while\n  still honouring the opt-out (`--no-mcp`, `--no-enrich`, `--cli-only`)\n  and federation template behaviour.\n\n`wd prime` is idempotent and safe to re-run — it reports what is\nalready configured and what is still missing. Pass\n`--agent {auto,claude,codex,copilot,all}` to force the active agent's row\ninto the matrix even when that framework has no files yet (e.g. a Codex user\nin a Claude-only checkout sees `codex: skill no, mcp no -\u003e wd bootstrap codex`\ninstead of silence). `auto` is the default and infers the agent from\nenvironment variables such as `CODEX_*`.\n\n## Trust model\n\nWeld's trust posture is explicit and narrow:\n\n- **Default**: bundled discovery reads source files and writes the local\n  graph (`.weld/graph.json`). It does not execute discovered application\n  code and does not open network connections.\n- **Safe mode**: when enabled with `--safe`, safe mode disables\n  project-local strategies (`.weld/strategies/`) and the `external_json`\n  adapter for `wd discover`, and refuses network/LLM enrichment providers\n  for `wd enrich`. Pass `wd discover --safe` to scan an untrusted\n  repository without executing any code from it; pass `wd enrich --safe`\n  to refuse network egress (every currently registered provider —\n  Anthropic, OpenAI, Ollama, Copilot CLI — is refused). Safe mode produces a stable\n  `[weld] safe mode: ...` stderr line for each refused path.\n- **Advanced strategies**: project-local strategies are Python modules\n  loaded at discovery time, and `strategy: external_json` executes\n  configured commands from `discover.yaml`. Only enable these on\n  repositories you trust.\n\nSee [SECURITY.md](SECURITY.md) for the full policy and reporting process.\n\n## Local telemetry\n\nWeld records the success or failure of every `wd` CLI invocation and every\nMCP tool call to a local-only file. There is no remote endpoint and no\nupload — the file never leaves your machine unless you explicitly export\nand share it.\n\n**What is recorded.** Each event is one JSON line with a strict allowlist\nof fields: subcommand or tool name, exit code, duration in milliseconds,\nand the exception class name on failure. Paths, query strings, error\nmessages, flag values, and usernames are never recorded. The redaction is\nenforced at write time, so the file on disk is already safe to attach to a\nbug report.\n\n**Where it lives.** In a single repo, the file is\n`\u003crepo\u003e/.weld/telemetry.jsonl`. In a polyrepo workspace, every event from\nthe root and from any child repo aggregates into\n`\u003cworkspace_root\u003e/.weld/telemetry.jsonl` — one shareable artifact per\nworkspace. Invocations outside any project (for example `wd --version` in\n`/tmp`) fall back to `${XDG_STATE_HOME:-~/.local/state}/weld/telemetry.jsonl`.\nThe file is gitignored and rotates at 1 MiB to keep the trailing 500 events.\n\n**How to opt out.** Any one of these disables recording:\n`WELD_TELEMETRY=off` in the environment, the `--no-telemetry` flag on a\nsingle invocation, or `wd telemetry disable` to write a persistent sentinel\nat the resolved root. Run `wd telemetry --help` for the full subcommand\nsurface (`status`, `show`, `path`, `export`, `clear`, `disable`, `enable`),\nand see [`docs/telemetry.md`](docs/telemetry.md) for the full event\nschema and design rationale.\n\n## Supported languages\n\nAll language strategies use tree-sitter and degrade gracefully when the\ngrammar package is not installed.\n\n| Language | Extraction surface | Grammar package |\n|---|---|---|\n| Python | modules, classes, functions, imports, call graph | `tree-sitter-python` |\n| TypeScript / JS | exports, classes, imports | `tree-sitter-typescript` |\n| Go | exports, types, imports | `tree-sitter-go` |\n| Rust | exports, types, imports | `tree-sitter-rust` |\n| C# | types, methods, properties, attributes, namespaces, using dependencies | `tree-sitter-c-sharp` |\n| C++ | exports, classes, imports, best-effort call graph | `tree-sitter-cpp` |\n| Java | classes, methods, annotations, imports, package dependencies | `tree-sitter-java` |\n| ROS2 | packages, nodes, topics, services, actions, parameters | (reuses Python + C++) |\n\nDiscovery also adds deterministic closure edges from files to source-backed\nsymbols and from import/include/use declarations to local files or external\npackage nodes across every listed language.\n\nTo enable tree-sitter support:\n\n```bash\nuv tool install \"configflux-weld[tree-sitter]\"\n```\n\nTo use the built-in semantic enrichment providers:\n\n```bash\nuv tool install \"configflux-weld[openai]\"     # or [anthropic], [ollama], or [llm]\n```\n\nThe `copilot-cli` provider needs no Python extra — install the standalone\nGitHub Copilot CLI binary (`copilot`) and run\n`wd enrich --provider copilot-cli`. Set `WELD_COPILOT_BINARY` to override\nthe binary path.\n\nFor a source-checkout install (contributors editing Weld itself), see\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\nAgents can also enrich nodes without provider extras or API keys by reading the\nrelevant source or documentation and writing reviewed enrichment manually:\n\n```bash\nwd stale\nwd context \"\u003cnode-id\u003e\"\nwd add-node \"\u003cnode-id\u003e\" --type \"\u003cnode-type\u003e\" --label \"\u003clabel\u003e\" --merge --props '{\"description\":\"...\",\"purpose\":\"...\",\"enrichment\":{\"provider\":\"manual\",\"model\":\"agent-reviewed\",\"timestamp\":\"\u003cISO-8601 UTC timestamp\u003e\",\"description\":\"...\",\"purpose\":\"...\",\"suggested_tags\":[\"lowercase\",\"tags\"]}}'\nwd graph validate\nwd graph stats\nwd graph communities --format markdown\n```\n\nManual enrichment writes `.weld/graph.json` directly and can be overwritten by\na later `wd discover --output .weld/graph.json`; refresh discovery before manual\nedits. Manual inferred edges should use explicit provenance such as\n`{\"source\": \"manual\"}` after the relationship is verified from source content.\n`wd graph communities --write` derives `.weld/graph-communities.json`,\n`.weld/graph-community-report.md`, and `.weld/graph-community-index.md`\nfrom the existing graph without modifying `.weld/graph.json`.\n\nWithout tree-sitter, the built-in Python module strategy and non-language\nstrategies (markdown, YAML, config, frontmatter) still work.\n\n## MCP\n\nWeld generates MCP config snippets for Claude Code, VS Code, Cursor, and\nCodex in the default install:\n\n```bash\nwd mcp config --client=claude\nwd mcp config --client=vscode\nwd mcp config --client=cursor\n```\n\nRunning the stdio MCP server requires the optional MCP SDK extra:\n\n```bash\nuv tool install \"configflux-weld[mcp]\"\npython -m weld.mcp_server --help\n```\n\nPoint your client at `python -m weld.mcp_server`:\n\n```json\n{\"mcpServers\": {\"weld\": {\"command\": \"python\", \"args\": [\"-m\", \"weld.mcp_server\"]}}}\n```\n\nSee **[docs/mcp.md](docs/mcp.md)** for the full tool reference, per-client\nconfigs, example prompts, troubleshooting, and the exact dependency model. See\nthe [platform support matrix](docs/platform-support.md) for per-client support\nstatus and runtime validation.\n\n## Discovery configuration\n\nWeld is driven by `.weld/discover.yaml`. Each entry maps a file pattern\nto an extraction strategy:\n\n```yaml\nsources:\n  - glob: \"src/**/*.py\"\n    type: file\n    strategy: python_module\n\n  - glob: \"docs/**/*.md\"\n    type: doc\n    strategy: markdown\n\n  - glob: \".github/workflows/*.yml\"\n    type: workflow\n    strategy: yaml_meta\n```\n\nRun `wd init` to generate a starter config, or write one by hand. See\nthe [Strategy Cookbook](weld/docs/strategy-cookbook.md) for the full list\nof bundled strategies.\n\n### `.weld/.gitignore`\n\n`wd init` and `wd workspace bootstrap` write a managed `.weld/.gitignore`\nthe first time they touch a `.weld/` directory (idempotent — never\noverwrites an existing file). Three policies are available:\n\n- **Default — config-only.** Tracks the source-of-truth config\n  (`discover.yaml`, `workspaces.yaml`, `agents.yaml`, `strategies/`,\n  `adapters/`, `README.md`) and ignores everything else weld writes,\n  including the generated graphs (`graph.json`, `agent-graph.json`),\n  graph-community reports (`graph-communities.json`,\n  `graph-community-report.md`, `graph-community-index.md`),\n  and per-machine state (`discovery-state.json`, `graph-previous.json`,\n  `workspace-state.json`, `workspace.lock`, `query_state.bin`). A\n  fresh contributor gets a clean `git status` after the first run.\n- **Track-graphs (opt-in team workflow for warm CI / warm MCP).** Pass\n  `--track-graphs` to widen the default so the canonical graphs are\n  committed alongside config. Use this when every contributor should\n  share a pre-built graph:\n\n  ```bash\n  wd init --track-graphs\n  wd workspace bootstrap --track-graphs\n  ```\n\n- **Ignore-all (opt-in).** Pass `--ignore-all` for early experimentation\n  or test installs where no weld state should be committed yet:\n\n  ```bash\n  wd init --ignore-all\n  wd workspace bootstrap --ignore-all\n  ```\n\n  This writes a heavy-handed `*` / `!.gitignore` so every weld file is\n  ignored.\n\n`--track-graphs` and `--ignore-all` are mutually exclusive; passing both\nis a usage error.\n\n**Migration from earlier versions.** Pre-existing `.weld/.gitignore`\nfiles written by older `wd init` / `wd workspace bootstrap` runs are\n**not** rewritten — the helper is idempotent. To pick up the new\ndefault, delete the file and re-run init:\n\n```bash\nrm .weld/.gitignore\nwd init                  # config-only default, generated graphs ignored\n# or wd init --track-graphs   to keep tracking the graphs as before\n```\n\nTo opt out entirely, just delete `.weld/.gitignore` after init — the\nskip-if-exists guard means it won't be recreated until the next init\nor bootstrap.\n\n### Custom strategies\n\nDrop a Python file in `.weld/strategies/` to extract repo-specific\nartifacts. The strategy signature:\n\n```python\ndef extract(root: Path, source: dict, context: dict) -\u003e StrategyResult:\n    ...\n```\n\nSee [examples/02-custom-strategy](examples/02-custom-strategy/) for a\nworking example that extracts TODO comments as graph nodes.\n\n## Polyrepo Federation\n\nWeld supports federated polyrepo workspaces where a root directory contains\nseveral child git repositories, each owning its own `.weld/` directory. The\nroot maintains a meta-graph of cross-repo relationships without duplicating\nchild content. Children remain portable and independently publishable.\n\n### Prerequisites\n\n- Each child repo has been initialized with `wd init` and has a\n  `.weld/graph.json`.\n- The workspace root directory contains the child repos as subdirectories\n  (nested git repositories).\n\n### Setting up a workspace\n\nRun `wd init` at the workspace root. When nested git repositories are\ndetected, weld automatically scaffolds `.weld/workspaces.yaml` alongside\nthe usual `discover.yaml`:\n\n```bash\ncd ~/workspace-root\nwd init                    # detects children, writes workspaces.yaml\nwd init --max-depth 2      # limit scan depth for large directory trees\n```\n\nThe `--max-depth` flag controls how many directory levels deep the scanner\nlooks for nested `.git` directories (default: 4).\n\n### workspaces.yaml format\n\nThe workspace registry lists every child repo and declares which cross-repo\nresolvers are active:\n\n```yaml\nversion: 1\nscan:\n  max_depth: 4\n  respect_gitignore: false\n  exclude_paths: [.worktrees, vendor, \"scratch/**\", \"generated/**/*.tmp\"]\nchildren:\n  - name: services-api\n    path: services/api\n    tags:\n      category: services\n  - name: services-auth\n    path: services/auth\n    tags:\n      category: services\ncross_repo_strategies: [service_graph]\n```\n\n- **version**: Schema version (currently `1`).\n- **scan**: Controls automatic child detection. `max_depth` sets how deep\n  the scanner walks; `respect_gitignore` opts scan-only children into Git\n  ignore rules; `exclude_paths` lists directory names, relative paths, or\n  glob patterns to skip. Explicit `children` entries remain authoritative\n  even when gitignored.\n- **children**: Each entry has a `path` (relative to the workspace root)\n  and an optional `name` (auto-derived from the path if omitted, e.g.\n  `services/api` becomes `services-api`). Optional `tags` provide\n  category metadata; optional `remote` records a clone URL.\n- **cross_repo_strategies**: Ordered list of resolvers that produce\n  cross-repo edges in the root graph. Currently available: `service_graph`.\n\n### Running discovery at the workspace root\n\n```bash\ncd ~/workspace-root\nwd discover --safe --output .weld/graph.json\n```\n\nWhen `workspaces.yaml` is present, `wd discover` operates in federation\nmode. It reads each child's `.weld/graph.json`, builds `repo:\u003cname\u003e` nodes\nfor every present child, and runs the declared cross-repo resolvers to emit\nedges between children. Children that are missing, uninitialized, or corrupt\ndegrade gracefully -- they are skipped and recorded in the workspace ledger\nbut do not block discovery.\n\nDiscovery is safe to run from a linked git worktree of the workspace root:\nthe federation pass falls back to the main worktree's checkout when sibling\nchild repos are not present at the worktree itself (ADR 0028). As a\ndefense-in-depth guard, federated discover refuses to overwrite an existing\nnon-empty `graph.json` with a 0-node meta-graph; pass `--allow-empty` to\nintentionally tear the workspace graph down.\n\n### Workspace status\n\nInspect the state of every registered child:\n\n```bash\nwd workspace status          # human-readable summary\nwd workspace status --json   # raw JSON ledger\n```\n\nExample output:\n\n```\nWorkspace status (3 children)\nCounts: present=2, missing=1, uninitialized=0, corrupt=0\nservices-api: present (refs/heads/main a1b2c3d4e5f6)\nservices-auth: present dirty (refs/heads/feature-x 7890abcdef01)\nservices-worker: missing\n```\n\nEach child shows its lifecycle status, git branch, HEAD SHA prefix, and\nwhether the working tree is dirty.\n\n### Sentinel files\n\nWeld uses two sentinel files to distinguish workspace roots from\nsingle-repo projects:\n\n| File | Purpose |\n|---|---|\n| `.weld/workspaces.yaml` | Workspace registry -- lists children and cross-repo strategies |\n| `.weld/workspace-state.json` | Workspace ledger -- lifecycle status, git SHA, graph hash per child |\n\nThe presence of `workspaces.yaml` activates federation mode in `wd discover`.\n`workspace-state.json` is written automatically during discovery and read by\n`wd workspace status`.\n\nWhen `.weld/workspaces.yaml` is present at the bootstrap target, `wd bootstrap`\nappends a federation paragraph to the copilot skill/instruction, codex skill,\nand claude command directing agents to pick a child via `wd workspace status`\nbefore querying inside it.\n\n### Cross-repo resolvers\n\nResolvers are plugins that analyze child graphs and emit typed edges across\nrepo boundaries. They are declared in the `cross_repo_strategies` list in\n`workspaces.yaml` and run in declaration order during root discovery.\n\n| Resolver | Description |\n|---|---|\n| `service_graph` | Matches HTTP client call sites in one repo to API endpoint definitions in another. Emits `invokes` edges with host, port, and path metadata. |\n\nResolvers are read-only with respect to child graphs -- they never modify\na child's `.weld/graph.json`. Output edges are deterministic: identical\ninput produces byte-identical edges across runs.\n\n### Rollback\n\nTo disable federation and return to single-repo behavior, delete the\nworkspace registry:\n\n```bash\nrm .weld/workspaces.yaml\n```\n\nThis returns weld to legacy single-repo discovery at the root. Child\nrepositories are untouched -- each child's `.weld/` directory, graph, and\nconfiguration remain intact and continue to work independently.\n\nOptionally, remove the generated ledger as well:\n\n```bash\nrm .weld/workspace-state.json\n```\n\n## CLI reference\n\n| Command | Description |\n|---|---|\n| `wd init` | Bootstrap `.weld/discover.yaml` (and `workspaces.yaml` when nested repos are detected); seed managed `.weld/.gitignore` (config-only default ignores generated graphs) |\n| `wd init --max-depth N` | Limit nested repo scan depth during init (default: 4) |\n| `wd init --respect-gitignore` | Skip scan-only nested repos ignored by Git when writing `workspaces.yaml`; explicit children can still be added later |\n| `wd init --track-graphs` | Seed `.weld/.gitignore` so canonical graphs (`graph.json` + `agent-graph.json`) stay tracked alongside config (warm-CI / warm-MCP workflow) |\n| `wd init --ignore-all` | Write a fully-ignoring `.weld/.gitignore` instead of the config-only default; mutually exclusive with `--track-graphs` |\n| `wd discover` | Run discovery, emit graph JSON (federation mode when `workspaces.yaml` is present); on success prints a one-line stderr summary `wrote N nodes / M edges -\u003e path (T.Ts)`, suppressed by `--quiet` |\n| `wd agents discover` | Scan AI customization assets and write `.weld/agent-graph.json`; text mode summarizes diagnostics per code and `--show-diagnostics` dumps the full list inline |\n| `wd agents rediscover` | Refresh `.weld/agent-graph.json` from a new static scan |\n| `wd agents list` | List discovered AI customization assets from `.weld/agent-graph.json` |\n| `wd agents explain \u003casset\u003e` | Explain one AI customization asset and its graph relationships |\n| `wd agents impact \u003casset\u003e` | Show affected Agent Graph assets for a proposed customization change |\n| `wd agents audit` | Audit AI customization assets for static consistency issues |\n| `wd agents plan-change \"\u003crequest\u003e\"` | Plan a static AI customization behavior change |\n| `wd agents viz` | Local read-only browser explorer for `.weld/agent-graph.json` |\n| `wd workspace status` | Show workspace child ledger: lifecycle status, git ref, dirty state |\n| `wd workspace status --json` | Emit the raw `workspace-state.json` payload |\n| `wd workspace bootstrap` | One-shot polyrepo bootstrap: init root + every nested child, recurse-discover, rebuild root meta-graph (config-only `.weld/.gitignore` default) |\n| `wd workspace bootstrap --respect-gitignore` | Skip scan-only child repos ignored by Git and persist `scan.respect_gitignore: true` into `workspaces.yaml` |\n| `wd workspace bootstrap --track-graphs` | Bootstrap and seed `.weld/.gitignore` in root and every child to track canonical graphs alongside config |\n| `wd workspace bootstrap --ignore-all` | Bootstrap and write a fully-ignoring `.weld/.gitignore` in root and every child; mutually exclusive with `--track-graphs` |\n| `wd build-index` | Regenerate file index |\n| `wd query \u003cterm\u003e` | Hybrid-ranked tokenized graph search (strict-AND first; OR fallback when AND yields nothing on multi-word phrases — envelope is tagged with `degraded_match=or_fallback`) |\n| `wd find \u003cterm\u003e [--limit N]` | Broad file-token search, separate from graph discovery; each hit carries an integer `score` (default `--limit 20`) |\n| `wd context \u003cid\u003e` | Node + neighborhood |\n| `wd path \u003cfrom\u003e \u003cto\u003e` | Shortest path |\n| `wd trace \u003cterm\u003e` | Startup/runtime and interaction slice around a term or node |\n| `wd impact \u003cpath-or-node\u003e` | Reverse-dependency blast radius |\n| `wd callers \u003csymbol\u003e` | Direct/transitive callers |\n| `wd viz` | Local read-only browser graph explorer |\n| `wd stale` | Check graph freshness |\n| `wd graph stats` | Graph statistics |\n| `wd graph communities [--format json\\|markdown] [--top N] [--write]` | Detect deterministic graph communities, report top-level hubs, and optionally write derived JSON/report/index artifacts (per ADR 0039: unresolved-symbol nodes are excluded from the projected subgraph) |\n| `wd stats` | Backward-compatible alias for `wd graph stats` |\n| `wd graph validate` | Validate graph against the contract |\n| `wd graph validate-fragment \u003cfile\u003e` | Validate imported graph fragments and warn on trace-inert semantics |\n| `wd validate` | Backward-compatible alias for `wd graph validate` |\n| `wd doctor` | Check setup health; exits 0 in directories that are not Weld projects yet |\n| `wd prime` | Setup status + per-framework agent surface matrix (skill / instruction / mcp) with fix commands; `--agent {auto,claude,codex,copilot,all}` forces an agent row even when its framework files are absent |\n| `wd scaffold` | Write starter templates |\n| `wd bootstrap` | Agent onboarding files |\n| `wd brief` | Agent context briefing |\n| `wd enrich` | LLM-assisted semantic enrichment |\n| `wd lint` | Lint the graph for architectural violations |\n\n`wd doctor` reports each finding at one of four levels: `[ok ]` for\nhealthy state, `[note]` for soft recommendations (a missing optional\nprovider, no MCP config), `[warn]` for a currently-degraded state (a\nstale graph, missing tree-sitter grammars), and `[fail]` for invalid\nsetup. Only `[fail]` raises the exit code; notes and warnings are\nvisible but never fatal. Each note carries a stable id (e.g.\n`(id: optional-copilot-cli-missing)`) that you can dismiss per project:\n\n```bash\nwd doctor --ack optional-copilot-cli-missing   # write to .weld/doctor.yaml\nwd doctor --unack optional-copilot-cli-missing # restore\nwd doctor --list-acks                          # list current dismissals\n```\n\nThe valid note ids are `mcp-config-missing`, `optional-mcp-missing`,\n`optional-anthropic-missing`, `optional-openai-missing`,\n`optional-ollama-missing`, and `optional-copilot-cli-missing`. The\n`copilot-cli` probe walks `WELD_COPILOT_BINARY` and `PATH` for the\nstandalone GitHub Copilot CLI binary, so its install hint points at\n[github.com/en/copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-cli)\nrather than a `pip install` line.\n\n`wd lint` also loads custom edge rules from `.weld/lint-rules.yaml` when\npresent:\n\n```yaml\nrules:\n  - name: no-api-to-internal\n    deny:\n      from: { type: file, path_match: \"api/**\" }\n      to: { type: file, path_match: \"internal/**\" }\n```\n\nRules can add an `allow` block with the same `from` / `to` selectors to\nexempt specific edges from a broader deny match.\n\nOutput is signal-first: the summary line counts violations per rule,\nhigh-signal rules (`no-circular-deps`, `boundary-enforcement`) print\nbefore noisier ones, and `orphan-detection` runs last. By default the\norphan rule suppresses `doc`, `config`, and test-file node types\n(intentional leaves in nearly every codebase) and the suppressed count\nis reported in the summary. Pass `--include-noisy` to surface every\norphan. Suppressed orphans on their own do not raise the exit code.\n\nRun `wd --help` for the full list.\n\nThe repository includes a canonical Agent System Maintainer skill at\n`.agents/skills/agent-system-maintainer/SKILL.md` and a GitHub Copilot\nAgent Architect at `.github/agents/agent-architect.agent.md`. They are\nordinary Agent Graph assets, so `wd agents discover`, `explain`, and\n`impact` can inspect them before future customization changes.\n\n### Edge provenance with `props.source`\n\n`wd add-edge` accepts a strict set of edge types (see\n`weld.contract.VALID_EDGE_TYPES`). When an agent, tool, or LLM emits an\nedge, stamp its origin under `props.source` so downstream consumers can\nfilter, rank, or audit tool-generated relationships. The `--props` help\ntext carries the canonical example: `--props '{\"source\":\"llm\",\"confidence\":\"inferred\"}'`.\nThe `source` value is free-form (agent name, tool name, `llm`,\n`manual`, strategy id); `confidence` follows the existing vocabulary\n(`definite`, `inferred`, `speculative`). This replaces the 0.3.0-era\n`--source` and `--relation` flags.\n\n## Examples\n\n- [01-python-fastapi](examples/01-python-fastapi/) — discover a FastAPI\n  project: routes, Pydantic models, module structure\n- [02-custom-strategy](examples/02-custom-strategy/) — write a project-local\n  strategy plugin that extracts TODO/FIXME comments\n- [04-monorepo-typescript](examples/04-monorepo-typescript/) — discover a\n  TypeScript monorepo: workspace packages, cross-package imports, shared types\n- [05-polyrepo](examples/05-polyrepo/) — set up a federated polyrepo\n  workspace: workspaces.yaml, cross-repo discovery, workspace status\n- [agent-graph-demo](examples/agent-graph-demo/) — inspect mixed AI\n  customization assets with `wd agents discover`, `list`, `audit`,\n  `explain`, `impact`, and `plan-change`\n\nFor a tour of what each command above actually prints, see\n[Graph visualization examples](docs/visualization-examples.md) — real\nterminal snippets captured against `wd 0.15.0`.\n\n## Install\n\n### Recommended: `uv tool install`\n\n```bash\nuv tool install configflux-weld\n\n# Verify\nwd --version\n```\n\nThis is the single recommended install path. `uv tool install` puts\n`wd` on your `PATH` in an isolated environment, is fast, and gives you a\nclear update story:\n\n```bash\nuv tool upgrade configflux-weld   # or: uv tool upgrade --all\n```\n\nDon't have `uv` yet? See the [uv install\ninstructions](https://docs.astral.sh/uv/getting-started/installation/).\n\nTo run the stdio MCP server, install the optional MCP extra:\n\n```bash\nuv tool install \"configflux-weld[mcp]\"\npython -m weld.mcp_server --help\n```\n\n`wd mcp config` does not require the extra; only the server process does.\n\n### Alternative install paths\n\nThe paths below are supported but secondary. Prefer `uv tool install` unless\nyou have a concrete reason to pick one of these.\n\n#### `pipx` (if you already standardize on pipx)\n\n```bash\npipx install configflux-weld\nwd --version\n```\n\nFunctionally equivalent to `uv tool install` for end users. Use whichever\ntool manager your team already has.\n\n#### `install.sh` (zero-dependency bootstrap)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/configflux/weld/main/install.sh | sh\n```\n\n`install.sh` is a POSIX shell script that detects a compatible Python (3.10\nthrough 3.13) and installs via `uv`, `pipx`, or `pip --user`, in that order\nof preference. Use it only when you don't have `uv` or `pipx` available and\ncan't install them first — for example, on a minimal CI image or a\nlocked-down host. It is idempotent (re-running upgrades an existing install)\nand honours a `.weld-version` file in the current directory or any ancestor\nto pin a specific release tag.\n\n#### From a local checkout (development)\n\nIf you want to edit Weld itself, use a source-checkout install. See\n[CONTRIBUTING.md](CONTRIBUTING.md) for the full developer setup, including\neditable installs and optional-extras commands for `tree-sitter`, `mcp`,\n`openai`, `anthropic`, `ollama`, and `llm`.\n\n#### From a Git URL\n\n```bash\npip install \"git+https://github.com/configflux/weld.git@main#subdirectory=weld\"\n```\n\nUseful for pinning an unreleased commit or branch.\n\n#### Raw source (no install)\n\nIf you cannot install anything, the module entrypoint works from a plain\ncheckout:\n\n```bash\npython -m weld --help\n```\n\n### Python compatibility\n\nRuntime installs support Python 3.10 through 3.13. Contributor builds and\nBazel tests use the Python 3.12 toolchain pinned in `MODULE.bazel`, so the\ndevelopment toolchain can be narrower than the runtime support window.\n\n## Release policy\n\n`main` is the source of truth for the next release: the version recorded\nin [`VERSION`](VERSION) and `weld/pyproject.toml` matches the latest\n`publish/vX.Y.Z` git tag, except during a deliberately-staged window\nwhere `main` is bumped ahead of the latest tag.\n\nThe drift shape that produced the v0.9.0 and v0.10.1 incidents -- `main`\nsilently regressing below the latest published wheel -- is now caught\npost-release by `tools/check_main_release_consistency.py` (ADR 0015\ncheck 11; runs as part of `/release-audit`). To document a deliberate\n\"`main` is ahead of the latest tag\" window, add a comment marker to\nthis README:\n\n```html\n\u003c!-- release-lag: 0.11.0 staged for 2026-05-12 launch window --\u003e\n```\n\nThe check then turns the lag into a `WARN` and surfaces the reason\ninstead of failing. Remove the marker when the matching tag is cut.\nSee [`docs/release.md`](docs/release.md) for the full release\nchecklist (the post-release consistency check is step 9).\n\n## Documentation\n\n- [Full toolkit guide](weld/README.md) — architecture, design limits,\n  roadmap\n- [Onboarding guide](weld/docs/onboarding.md)\n- [Agent workflow](weld/docs/agent-workflow.md) — when to use each\n  retrieval surface\n- [Agent Graph](docs/agent-graph.md) — static map of the AI\n  customization layer (agents, skills, prompts, hooks, MCP servers)\n- [Graph visualization examples](docs/visualization-examples.md) —\n  real terminal output: monorepo graph, polyrepo `repo:` nodes,\n  Agent Graph, MCP config snippet\n- [Platform support matrix](docs/platform-support.md) — per-platform\n  support and runtime-validation status\n- [Performance notes](docs/performance.md) — discovery and query\n  timings on synthetic 1k/10k/100k single repos and polyrepo workspaces,\n  with a reproducible recipe\n- [Strategy cookbook](weld/docs/strategy-cookbook.md)\n- [Glossary](weld/docs/glossary.md)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Weld is currently maintainer-led.\nIssues, bug reports, demo repos, documentation improvements, and strategy\nproposals are welcome. For larger changes, please open an issue first so we\ncan align on scope before implementation.\n\n## License\n\nApache License, Version 2.0 — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconfigflux%2Fweld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconfigflux%2Fweld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconfigflux%2Fweld/lists"}