Options

Arguments and Options

Use UCAgent:

ucagent <workspace> <dut_name> {options}

Inputs

• workspace: working directory:
  • workspace/<DUT_DIR>: device under test (DUT), i.e., the Python package <DUT_DIR> exported by the picker; e.g., Adder
  • workspace/<DUT_DIR>/README.md: natural‑language description of verification requirements and goals for this DUT
  • workspace/<DUT_DIR>/*.md: other reference documents
  • workspace/<DUT_DIR>/*.v/sv/scala: source files used for bug analysis
  • Other verification‑related files (e.g., provided test cases, requirement specs, etc.)
• dut_name: the name of the DUT, i.e., <DUT_DIR>, for example: Adder

Outputs

• workspace: working directory:
  • workspace/Guide_Doc: guidance and documents followed during the verification process
  • workspace/uc_test_report: generated Toffee‑test report
  • workspace/unity_test/tests: auto‑generated test cases
  • workspace/*.md: generated docs including bug analysis, checkpoints, verification plan, and conclusion

See also the detailed outputs in Introduction.

Positional Arguments

Execution and Interaction

Config and Templates

Planning and ToDo

ToDo Tools Overview & Examples

Note: ToDo tools are for enhancing model planning; users can define the model’s ToDo list. This feature requires strong model capability and is disabled by default.

Enabling: use --use-todo-tools in any mode; or in standard mode use --force-todo to force enable and include ToDo info in each round.

Conventions and limits: step indices are 1‑based; number of steps must be 2–20; length of notes and each step text ≤ 100; exceeding limits will be rejected with an error string.

Tool overview

Invocation examples (MCP/internal tool call, JSON args):

{
	"tool": "CreateToDo",
	"args": {
		"task_description": "Complete verification closure for Adder core functions",
		"steps": [
			"Read README and spec, summarize features",
			"Define checkpoints and pass criteria",
			"Generate initial unit tests",
			"Run and fix failing tests",
			"Fill coverage and output report"
		]
	}
}

{
	"tool": "CompleteToDoSteps",
	"args": { "completed_steps": [1, 2], "notes": "Initial issues resolved, ready to add tests" }
}

{ "tool": "UndoToDoSteps", "args": { "steps": [2], "notes": "Step 2 needs checkpoint tweaks" } }

{ "tool": "ResetToDo", "args": {} }

{ "tool": "GetToDoSummary", "args": {} }

{ "tool": "ToDoState", "args": {} }

External and Embedding Tools

Logging

MCP Server

Stage Control and Safety

Version and Check

Example

python3 ucagent.py ./output Adder \
	\
	-s \
	-hm \
	-im enhanced \
	--tui \
	-l \
	--loop-msg 'start verification' \
	--seed 12345 \
	--sys-tips '按规范完成Adder的验证' \
	\
	--config config.yaml \
	--template-dir ./templates \
	--template-overwrite \
	--output unity_test \
	--override 'conversation_summary.max_tokens=16384,conversation_summary.max_summary_tokens=2048,conversation_summary.use_uc_mode=True,lang="zh",openai.model_name="gpt-4o-mini"' \
	--gen-instruct-file GEMINI.md \
	--guid-doc-path ./output/Guide_Doc \
	\
	--use-todo-tools \
	\
	--ex-tools 'SqThink,AnotherTool' \
	--no-embed-tools \
	\
	--log \
	--log-file ./output/ucagent.log \
	--msg-file ./output/ucagent.msg \
	\
	--mcp-server-no-file-tools \
	--mcp-server-host 127.0.0.1 \
	--mcp-server-port 5000 \
	\
	--force-stage-index 2 \
	--skip 5 --skip 7 \
	--unskip 6 \
	--nw ./output/Adder ./output/unity_test

• Positional arguments
  • ./output: workspace working directory
  • Adder: dut subdirectory name
• Execution and interaction
  • -s: stream output
  • -hm: human intervention on start
  • -im enhanced: enhanced interaction mode (with planning and memory)
  • –tui: enable TUI
  • -l: enter loop immediately after start
  • –loop/–loop-msg: inject first message when entering loop
  • –seed 12345: fix random seed
  • –sys-tips: custom system prompt
• Config and templates
  • –config config.yaml: load project config from config.yaml
  • –template-dir ./templates: set template directory to ./templates
  • –template-overwrite: allow overwrite when rendering templates
  • –output unity_test: output directory name unity_test
  • –override ‘…’: override config keys (dot‑path=value, multiple comma‑separated; string values require inner quotes and wrap the whole with single quotes); the example sets conversation summary limits, enables trimming, sets doc language to Chinese, and model name to gpt‑4o‑mini
  • -gif/–gen-instruct-file GEMINI.md: generate external collaboration guide at <workspace>/GEMINI.md
  • –guid-doc-path ./output/Guide_Doc: customize Guide_Doc directory as ./output/Guide_Doc
• Planning and ToDo
  • –use-todo-tools: enable ToDo tools and force attaching ToDo info
• External and embedding tools
  • –ex-tools ‘SqThink,AnotherTool’: enable external tools SqThink,AnotherTool
  • –no-embed-tools: disable built‑in retrieval/memory tools
• Logging
  • –log: enable log file
  • –log-file ./output/ucagent.log: set log output file to ./output/ucagent.log
  • –msg-file ./output/ucagent.msg: set message log file to ./output/ucagent.msg
• MCP Server
  • –mcp-server-no-file-tools: start MCP (without file tools)
  • –mcp-server-host: server listen address 127.0.0.1
  • –mcp-server-port: server listen port 5000
• Stage control and safety
  • –force-stage-index 2: start from stage index 2
  • –skip 5 –skip 7: skip stage 5 and stage 7
  • –unskip 7: unskip stage 7
  • –nw ./output/Adder ./output/unity_test: restrict writable paths to ./output/Adder and ./output/unity_test
• Notes
  • –check and –version exit immediately, not combined with run
  • –mcp-server and –mcp-server-no-file-tools are mutually exclusive; here we choose the latter. Path arguments (e.g., –template-dir/–guid-doc-path/–nw) must exist, otherwise an error occurs
  • String values in –override must be quoted, and wrap the whole argument in single quotes to prevent the shell from consuming the inner quotes (the example already does this)