3. 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.

Two kinds of command are available. latticemind run is the one-shot interface: one prompt, one pipeline turn, one JSON response, the same engine as latticemind quick. latticemind research drives a research conversation from a script, one message at a time (see Drive a research conversation from a script).

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.

3.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.

3.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.

3.3. Inspect an existing project without changing it

The inspection command reads a latticemind quick project’s recorded workflow, calculation status, report excerpt and indexed 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 add nothing to the project’s history and do not rewrite solver inputs or reports.

3.4. Run one prompt without opening an interactive interface

latticemind run is the one-shot interface. It creates or continues a latticemind quick project, plans the work, writes and validates the solver inputs, 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 does not run the solver by default. It writes the same project files as an interactive latticemind quick turn: the solver inputs, helper scripts, validation diagnostics and a report.

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.

3.5. Drive a research conversation from a script

latticemind research sends messages to a research conversation and reads its state, for agents that want the conversational runtime rather than the one-shot pipeline. Run it in the project folder:

latticemind research new --json
latticemind research send --session <id> --message "Do a PBE SCF for silicon." --json
latticemind research status --session <id> --json
latticemind research events --session <id> --json
latticemind research report --session <id> --json

new prints the conversation’s session ID. send delivers one message; chat --message "..." does the same and also runs the turn in this process. status shows the turn, the projects, the runs and any pending permission request without a model call. A launch still needs permission: latticemind research approve or deny answers the pending request with the exact values status shows (see latticemind research approve --help). --json is always used except for an interactive chat.

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

latticemind run uses the same setup as the terminal and the browser. Configure a valid LatticeMind license, and a RESCU license on the computer that executes RESCU. Configure a NanoDCAL license when the selected solver is NanoDCAL, and provide the NanoDCAL NeutralAtomDatabase obtained from the Nanoacademic portal. Choose the model with latticemind setup (or /model in an interactive session), or set the provider and its key yourself as described in Connecting your AI model.

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.

3.7. 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 run failed; inspect `diagnostics` and the preserved project path.