2. Using LatticeMind from Codex, Claude, and shell agents

Codex, Claude, and other agents that can run shell commands can discover and operate LatticeMind without learning its interactive screen layout. The commands on this page print plain text by default. Add --json when another program will read the result.

The discovery commands do not require a solver license or an AI-provider key. They are designed to work while an agent is first examining a computer and deciding how LatticeMind should be used.

2.1. Let an agent discover the installation

Ask the agent to run these commands in order:

latticemind --version
latticemind capabilities --json
latticemind docs "how do I configure a solver and start a project?"
latticemind doctor --json

capabilities returns the shell commands, the interactive slash commands, supported solvers, JSON field names, exit codes, and the solver-execution approval rule. docs searches LatticeMind, RESCU, and NanoDCAL reference text and infers the corpus from the question. doctor checks the selected solver command, project output directory, Web UI assets, and remote-profile configuration without launching a solver or opening an SSH connection.

2.2. Search LatticeMind and solver documentation

Use a natural-language question. The default response contains one concise answer and its source:

latticemind docs "How do I configure a NanoDCAL NeutralAtomDatabase?"
latticemind docs "What does info.savepath control?"
latticemind docs "What values can calculation.SCF.mixMethod use?"
latticemind docs "How do I resume a failed Slurm calculation?"

docs recognizes NanoDCAL markers such as calculation.SCF and NeutralAtomDatabase, RESCU markers such as info.savepath and kpoint.gridn, and LatticeMind command/interface names. If those markers do not identify one corpus, it searches all three. --corpus auto is the default; --corpus latticemind, rescu, nanodcal, or all overrides the choice.

Add --json for a compact JSON envelope containing the inferred corpus and up to three excerpts. Add --verbose to show full fields for those excerpts, including scores, distribution names, and corpus counts. Use --limit N to change the maximum number of returned excerpts:

latticemind docs "What does info.savepath control?" --json
latticemind docs "What does info.savepath control?" --verbose
latticemind docs "What does info.savepath control?" --verbose --limit 6

An agent can read an exact LatticeMind page when it needs the full wording:

latticemind docs --list
latticemind docs --source installation/solver_setup.rst

--source is limited to this LatticeMind user manual. It does not return a complete RESCU or NanoDCAL page. A source checkout can search approved .rst or .txt excerpts from its local solver mirrors. A wheel instead uses the sanitized RESCU text under rescu_agent/database/rescu and the hand-reviewed NanoDCAL keyword/calculation-name schema. The raw RESCU, NanoDCAL, and VASP documentation mirrors are not included in the wheel.

The solver search reads documentation text only. It does not index Python, shell, C/C++, MATLAB, notebook, raw HTML, raw/, generated/, or extracted/ files. A document containing a private-key or recognized API-token signature is skipped, and a Windows, Linux, or macOS user-home path in an excerpt is replaced with <user-home>. latticemind docs --list --json reports corpus counts and these exclusions without returning local solver-mirror paths.

2.3. Inspect an existing project without changing it

The inspection command reads the project path, project_state.json, calculation_status.json, artifact_registry.json, report excerpt, and indexed project files:

latticemind project inspect ./my-silicon-project --json

For a specific question, combine those project files with relevant LatticeMind, RESCU, and NanoDCAL documentation excerpts:

latticemind project ask \
  "Which calculation failed, which output is stale, and how should I continue it?" \
  --project ./my-silicon-project --json

Both commands are read-only. They do not append conversation.jsonl or project_events.jsonl, and they do not rewrite solver inputs or reports.

2.4. Run one prompt without opening an interactive interface

latticemind run creates or continues a normal LatticeMind project, runs the planner, writes solver inputs, validates them, and returns the report and exact project path in one response:

latticemind run \
  "Do a PBE SCF and band structure calculation for silicon." \
  --solver rescu --json

The one-shot command disables solver execution by default. It may write the same project files as an interactive planning turn, including project_state.json, project_events.jsonl, project_root/inputs/*, helper scripts, validation diagnostics, and report.md.

Continue the returned project path with a second prompt:

latticemind run \
  "Increase the SCF k-point mesh to 10 by 10 by 10." \
  --project ./latticemind_outputs/<returned-project> --solver rescu --json

Permit a solver launch only when that is the intended action:

latticemind run \
  "Run the validated silicon workflow and prepare the final figures." \
  --project ./latticemind_outputs/<returned-project> \
  --solver rescu --execute --approve-execution --json

Both execution flags are required. With neither flag, LatticeMind plans and validates without launching RESCU, NanoDCAL, or VASP. With exactly one flag, the command exits before changing a project. With both flags, the normal validator and launch-readiness checks still run before the solver command.

2.5. Licenses and provider settings for one-shot work

latticemind run uses the same setup as the Dashboard and Web UI. Configure a valid RESCU license for LatticeMind and RESCU execution. Configure a separate NanoDCAL license when the selected solver is NanoDCAL, and provide the NanoDCAL NeutralAtomDatabase obtained from the Nanoacademic portal. Select an AI provider with RESCU_LLM_PROVIDER and configure that provider’s key, or use a configured local Ollama endpoint.

If the license or provider check fails, the JSON response uses ok: false, places the explanation in diagnostics, and exits with code 3. Existing project files are preserved.

2.6. Read the JSON response and exit code

Machine-readable responses use the same six top-level fields:

{
  "schema_version": 1,
  "command": "project.inspect",
  "ok": true,
  "data": {},
  "diagnostics": [],
  "next_actions": []
}

An agent should check ok first, read the command-specific data object, report every diagnostics entry, and use next_actions only after it has checked that the suggested path and action match the user’s request.

Exit code	Meaning
`0`	The command completed successfully.
`2`	A command name, argument, or execution-approval flag was invalid.
`3`	The license or selected AI provider needs configuration.
`4`	The requested project path or manual page was not found.
`5`	The one-shot graph run failed; inspect `diagnostics` and the preserved project path.