Metadata-Version: 2.4
Name: clawmind
Version: 0.1.1
Summary: Task-state-machine-first runner for Logseq-driven workflows.
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: flashtext>=2.7

# 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

<video src="./logseq_Edemo.mp4" controls></video>

## How It Works

  ClawMind turns a Logseq task into a controlled workflow:

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

```mermaid
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

```text
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:

```env
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:

```powershell
uv sync
```

To install as a CLI:

```powershell
pip install -e .
```

If you are not using `uv`, use:

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

## Run

**Persistent worker**

```powershell
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:

```powershell
clawmind version
```

Show installation info:

```powershell
clawmind install-info
```

Upgrade:

```powershell
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
