Model a biGENIUS-X project with Claude Code
Applies to
License: MCP Server
Describe in business terms what your model needs, and Claude Code plans and builds the model objects with the biGENIUS-X MCP server. Use it to build a slice from a discovery or to change an existing model. Afterwards the changed model files are in your Git branch, ready for review in biGENIUS-X.
Prerequisites
- Claude Code with the plugin
bigenius-x-modeling, signed in. See Set up Claude Code for biGENIUS-X. - A branch of your own, checked out in your clone of the metadata repository. See Start modeling in a Branch.
- The source systems and discoveries the model needs, already in the project and pulled into your clone, so that its
discoveries/folder contains them. See Add a Source System and Add a Discovery.
Model with Claude Code
- Open Claude Code in the root folder of the repository (the folder with
project.yml) and describe what you need in business terms. Claude uploads the project files into a workspace on the server: it callsopen_workspaceand runs the upload command it returns. - The upload command normally runs without a prompt. If Claude Code asks, approve it when it is a
tarandcurlcommand with amcp.bigenius-x.comURL. - Read the plan. Claude reads the model objects, the discovery and the model object types your generator offers. It shows the model objects per layer with business keys, relationships and historization. The plugin's skill tells Claude to wait for your confirmation and to ask when grain, life cycle, historization or the formula of a measure is unclear. Correct the plan before you confirm it.
- Confirm the plan. Claude builds layer by layer from the sources upward, a small slice through all layers first. After each layer it runs
validate_project, fixes errors and reports warnings to you. - After each layer, Claude calls
download_changesand runs the download command, which writes the changes into your working tree. When files must be deleted, it also runs a delete command; the plugin never allows delete commands without a prompt, so Claude Code asks you first. - At the hand-over, Claude lists the new and changed model objects, open warnings and its assumptions. It asks whether to run the semantic model validation (
validate_semantic_model) or the architecture model calculation (calculate_architecture_model); either runs only when you agree. The calculation sends the workspace files to biGENIUS-X and replaces the architecture model of the project for the branch Claude names,mainwhen it names none. - Review the diff, then commit and push the branch.
- Open the branch in biGENIUS-X, check the model objects and generate the artifacts. See Generate artifacts.
- When biGENIUS-X reports findings, paste them into Claude Code and ask it to fix them.
Tools you see in the chat
- Open the project:
open_workspace, then the upload command;sync_workspaceuploads again. - Read:
list_project_objects,list_views,show_project_object,get_generator_catalog,describe_type. - Build:
create_model_object,add_terms,add_relationship,build_dataflow, often grouped inrun_batch. - Check:
validate_project. - Write back:
download_changes, then the download command. - On request only:
validate_semantic_model,calculate_architecture_model.
Edit model files by hand
You can edit expressions in mappings and filters, descriptions and properties directly in the YAML files. Edit only after Claude has downloaded its changes, then tell Claude, so that it uploads the files again with sync_workspace. Leave model objects, terms, relationships and business keys to the tools. The tools also create the derived content, such as foreign key terms, hash keys, Default Terms and mapping stubs, which a manual edit leaves out.
Work effectively with Claude
- Start small: build one business concept, for example Customer, through all layers, check it in biGENIUS-X, then continue.
- Answer questions in business terms ("a customer can have several addresses; only the current one counts"), not with the model object to build.
- Name the Dataflow Modeling View. Without one, new model objects go to the default view. The tools place model objects only on Dataflow Modeling Views; add them to a Relationship Modeling View in biGENIUS-X.
- Ask explicitly when existing model objects should change. The skill tells Claude to change them only on request.
- Start a new session for a new task. Long sessions lose precision.
Example
Example: a Data Vault and Mart project with the discovery CRM. The prompts show wording; which model object types exist depends on your generator.
Plan the Raw Vault for customer and account from the CRM discovery. Show me the business keys and relationships first.
After you confirm the plan, ask for the next slice:
Build a Customer dimension in the mart from the Raw Vault. Address changes are historized. Validate after each layer.
Other prompts that work in every project:
Which layers and model objects does the project have? Show me Customer with its terms and relationships. Rename the term CUST_NBR to CustomerNumber in all objects. biGENIUS-X reports these findings: <findings>. Fix them.
Replace <findings> with the findings that biGENIUS-X shows.
Check the result
git status lists the changed files under modelobjects/ and views/. After you push the branch and open it in biGENIUS-X, the new model objects appear in their view, and the validation of the branch shows no errors. See Validate a Local Branch.
Failure symptoms and recovery
The workspace has expired
Message: Workspace <workspace ID> does not exist or has expired (2 hours without use). Call open_workspace.
Cause: the server deletes a workspace after 2 hours without use.
Fix: ask Claude to open the project again. Changes that were downloaded are already in your working tree.
More symptoms, such as a refused model object type, are in MCP server troubleshooting.
Related articles
- Previous: Set up Claude Code for biGENIUS-X, Start modeling in a Branch, Add a Discovery
- Next: Generate artifacts
- See also: biGENIUS-X MCP server, MCP server troubleshooting, Add a Source System, Validate a Local Branch