{"id":49281797,"url":"https://github.com/configflux/weld","last_synced_at":"2026-04-25T19:01:11.065Z","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-23T18:44:33.000Z","size":1100,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T20:24:32.445Z","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":null,"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-23T18:44:34.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":3,"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":32273223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: 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-04-25T19:01:11.052Z","avatar_url":"https://github.com/configflux.png","language":"Python","readme":"# Weld\n\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**Try it in 5 minutes →** [docs/tutorial-5-minutes.md](docs/tutorial-5-minutes.md) walks through `wd init`, `discover`, `brief`, `query`, `context`, and `path` against 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 files, `.weld` configs, and committed git history -- ready for `wd discover`. If you have Weld installed but no source checkout, the same demos are available through the CLI: `wd demo list`, `wd demo monorepo --init \u003cdir\u003e`, `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 lives in `.weld/`\n  (config, graph, strategies) and expects to be committed alongside your\n  code. If that is 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 you commit with your code. 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- **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++, 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\nwd discover --output .weld/graph.json\n\n# Query the graph\nwd query \"authentication\"\nwd find \"login\"\nwd context file:src/auth/handler\nwd viz --no-open\nwd stale\n```\n\nTry it on a real example: [examples/04-monorepo-typescript](examples/04-monorepo-typescript/) (monorepo) · [examples/05-polyrepo](examples/05-polyrepo/) (polyrepo federation).\n\nSample output (`wd query \"auth\"` — trimmed):\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\"\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.\nWeld discovers common AI customization formats and exposes them through a\nlocal graph; the\n[Agent Graph guide](docs/agent-graph.md) documents node and edge types,\nauthority and drift, and the read-only-first policy, and runtime behavior is\nvalidated per client in the\n[platform support matrix](docs/platform-support.md).\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 — 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## 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| ROS2 | packages, nodes, topics, services, actions, parameters | (reuses Python + C++) |\n\nTo enable tree-sitter support:\n\n```bash\npip install -e \"weld/[tree-sitter]\"\n```\n\nTo use the built-in semantic enrichment providers:\n\n```bash\npip install -e \"weld/[openai]\"     # or [anthropic], [ollama], or [llm]\n```\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\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\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### 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  exclude_paths: [.worktrees, vendor]\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; `exclude_paths` lists directories to skip.\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 --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\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) |\n| `wd init --max-depth N` | Limit nested repo scan depth during init (default: 4) |\n| `wd discover` | Run discovery, emit graph JSON (federation mode when `workspaces.yaml` is present) |\n| `wd agents discover` | Scan AI customization assets and write `.weld/agent-graph.json` |\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 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 build-index` | Regenerate file index |\n| `wd query \u003cterm\u003e` | Hybrid-ranked tokenized graph search |\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 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 stats` | Backward-compatible alias for `wd graph stats` |\n| `wd graph validate` | Validate graph against the contract |\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 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\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.8.1`.\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\nFor contributors editing Weld itself:\n\n```bash\npip install -e weld/\nwd --help\n```\n\nFor tree-sitter language support (Go, Rust, TypeScript, C++):\n\n```bash\npip install -e \"weld/[tree-sitter]\"\n```\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## 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","funding_links":[],"categories":[],"sub_categories":[],"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"}