clawmind 0.1.2

Task-state-machine-first runner for Logseq-driven workflows.

ClawMind -- Logseq AI Coworker

From chat to interaction. You’re not talking to AI—you’re thinking with yourself.

ClawMind is a Logseq-native workflow runner for individuals who need AI execution with human oversight. It turns everyday notes, questions, and task blocks into a controlled execution flow that is understandable, replayable, and auditable.

Unlike a generic AI chat tool, ClawMind separates flow control, reasoning, and writeback into explicit system boundaries. Work Runner manages task intake and state transitions, Codex Runner handles reasoning-heavy execution, and the Deterministic Executor writes results back in a repeatable way.

Why ClawMind

ClawMind is designed for knowledge workflows where correctness, traceability, and operational clarity matter.

• Logseq remains the human-facing workflow surface.
• AI execution is bounded by explicit runtime and writeback rules.
• Every run can leave reproducible audit evidence in run_logs/ and runtime_artifacts/.
• The system is built to reduce ad hoc task handling and turn repeated thinking work into durable process assets.

Demo

How It Works

ClawMind turns a Logseq task into a controlled workflow:

DOING -> WAITING -> execute -> writeback -> audit

sequenceDiagram
    participant L as Logseq Task
    participant W as Work Runner
    participant C as Codex Runner
    participant D as Deterministic Executor

    L->>W: DOING task detected
    W->>W: Normalize id and lock as WAITING
    W->>C: Build context and execute
    C-->>W: Return structured result
    W->>D: Apply deterministic writeback
    D-->>L: Update answer and links
    W-->>L: Record audit trail

Roles

• Work Runner is the flow controller. It scans DOING tasks, normalizes id::, moves tasks into WAITING, builds execution context, and coordinates the full run.
• Codex Runner is the reasoning engine. It handles the AI-heavy part of the task and returns structured output, but it does not directly mutate Logseq pages or task state.
• Deterministic Executor is the writeback layer. It applies results in a repeatable way, writes answer pages and journal links, and helps preserve idempotency and auditability.

Core Guarantees

• stable id:: primary key
• runtime / knowledge domain separation
• writeback idempotency
• AI does not write to Logseq directly

Project Structure

app/                Core application code
tests/              Unit tests
run_logs/           Execution audit records
runtime_artifacts/  Execution artifacts

Environment Requirements

• WINDOWS OS
• Install Codex CLI (Plus / month)
• Install Logseq
• Python 3.13+

Configuration

The program resolves configuration files in this order:

1. The file specified by CLAWMIND_ENV_PATH
2. .env in the current working directory
3. .env in the project root

Common settings:

LOGSEQ_PATH=<your Logseq root directory>
CODEX_CLI_PATH=<path to the codex executable>
JOURNAL_SCAN_DAYS=<optional>
MAX_RETRIES=<optional>
CODEX_TIMEOUT_SECONDS=<optional>

Variable notes

• JOURNAL_SCAN_DAYS
  • Unset = scan all journals
  • Set = scan only the most recent N days
• MAX_RETRIES defaults to 2
• CODEX_TIMEOUT_SECONDS defaults to 300 seconds
• Example CODEX_CLI_PATH: C:\Users\<Username>\AppData\Local\nvm\v24.11.0\codex.cmd

Installation

Development environment:

uv sync

To install as a CLI:

pip install -e .

If you are not using uv, use:

python -m venv .venv
.venv\Scripts\activate
pip install -e .

Run

Persistent worker

clawmind run-worker

Stop

Ctrl+C

On startup, the program prints config_source and env_path so you can verify which configuration source was actually used.

CLI Helper Commands

Check version:

clawmind version

Show installation info:

clawmind install-info

Upgrade:

clawmind upgrade --method auto
clawmind upgrade --method pipx
clawmind upgrade --method uv
clawmind upgrade --method pip

Method mapping:

• pipx install clawmind -> clawmind upgrade --method pipx
• uv tool install clawmind -> clawmind upgrade --method uv
• pip install clawmind -> clawmind upgrade --method pip

Roadmap

• Support macOS.
• Support Gemini CLI and Claude CLI.

Contact

• X.com @pigslybear