Gait Session Tracking

GAIT Session Tracking

This skill is mandatory. Every NetClaw session MUST begin with gait_branch and end with gait_log.

How to Call the Tools

The GAIT MCP server provides the lifecycle tools below (discover tools/list for the complete installed inventory). Call them via mcp-call:

Check Repository Status

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_status '{}'

Returns current branch, uncommitted changes, and repository state.

Initialize a New GAIT Repository

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_init '{"path":"/absolute/path/to/project"}'

Creates a new GAIT repository if one does not already exist. Supply the actual absolute project path; do not run against the filesystem root. Run once during initial setup, then verify gait_status names the intended root.

Create a New Branch (SESSION START)

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_branch '{"name":"health-check-r1-2026-02-21"}'

Creating a branch does not switch to it. Call gait_checkout with the same name and verify gait_status before recording turns. Every session begins here. Use a descriptive branch name that includes the action type, target device(s), and date. Examples:

• health-check-r1-2026-02-21
• ospf-troubleshoot-core-2026-02-21
• config-deploy-acl-update-2026-02-21
• netbox-reconcile-site-hq-2026-02-21
• security-audit-dmz-2026-02-21

Switch to an Existing Branch

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_checkout '{"name":"health-check-r1-2026-02-21"}'

Use this to resume a previous session or switch context between parallel investigations.

Record an AI Turn (PRIMARY RECORDING TOOL)

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_record_turn '{"user_text":"User asked to check CPU on R1","assistant_text":"Ran show processes cpu sorted. CPU 5-min avg: 12%. Status: HEALTHY.","artifacts":[{"path":"show_proc_cpu_r1.txt","content":"Sanitized evidence reference; raw evidence retained locally."}]}'

Record a turn after every significant action. Each turn captures:

• user_text: What was asked or what triggered the action
• assistant_text: What data was collected and what the result was
• artifacts: List of {"path": "...", "content": "..."} objects (optional; use sanitized content only)

View Commit History (SESSION END)

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_log '{}'

Every session ends here. Display the full audit log before concluding. This provides the user with a complete record of everything that happened.

Show Commit Details

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_show '{"commit":"HEAD"}'

Inspect a specific commit to see its full content. Use HEAD, HEAD~1, or a commit hash.

Pin Important Commits

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_pin '{"commit":"HEAD","last":false,"note":"pre-change-baseline"}'

Mark critical moments in a session so they can be easily found later. Common pin labels:

• pre-change-baseline -- state before any modifications
• post-change-verified -- state after changes are validated
• critical-finding -- an important discovery during investigation
• rollback-point -- safe state to return to if needed

Summarize and Squash Turns

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_record_turn '{"user_text":"Session summary","assistant_text":"Summarize findings, changes, verification and remaining gaps.","note":"session-summary"}'

Do not squash immutable operational audit history. Record an additive summary using gait_record_turn instead. The server exposes squashing for other use cases; its availability is not authorization to rewrite this project's audit trail.

Mandatory Session Lifecycle

Every NetClaw session follows this exact lifecycle:

1. Session Start -- Create Branch

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_branch '{"name":"ACTION-TYPE-TARGET-DATE"}'
python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_checkout '{"name":"ACTION-TYPE-TARGET-DATE"}'
python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_status '{}'

2. During Session -- Record Every Turn

After each meaningful action (show command, config change, API call, verification), record a turn:

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_record_turn '{"user_text":"WHAT_WAS_ASKED","assistant_text":"WHAT_DATA_COLLECTED_AND_WHAT_CHANGED_AND_VERIFICATION_RESULT","artifacts":[]}'

Record format guidelines:

• user_text: State clearly what the user asked or what triggered the action
• assistant_text: Include three parts:
  1. What data was collected (commands run, API responses)
  2. What changed (config applied, ticket created, NetBox updated)
  3. Verification result (HEALTHY/WARNING/CRITICAL, pass/fail, before/after diff)
• artifacts: List any files generated (logs, configs, diagrams, reports)

3. Session End -- Display Log

python3 $MCP_CALL "python3 -u $GAIT_MCP_SCRIPT" gait_log '{}'

Always show the session log to the user so they have a complete record.