How LoopX Projects Public-Safe Evidence Through the Lark Kanban Adapter

LoopX uses the hidden .loopx/ directory as its source of truth for project state, then sanitizes all evidence through _public_safe_text() before projecting it to Lark Kanban boards via the sync_loopx_todos_to_lark_kanban() adapter.

The huangruiteng/loopx repository implements a secure evidence-projection pipeline that keeps sensitive data local while sharing sanitized progress updates. By treating .loopx/ as the authoritative store and applying redaction rules before network transmission, LoopX ensures that public Kanban boards contain only safe, non-sensitive information.

The Source of Truth: The .loopx/ Directory

LoopX designates the .loopx/ directory at the project root as the single source of truth for all configuration, state files, and local evidence. This hidden directory contains:

• Kanban configuration (lark-kanban.json) storing base tokens, table IDs, and view mappings
• Todo state files tracking user and agent task progress
• Local record mappings that tie LoopX internal IDs to Lark record IDs for incremental syncs

Because this directory remains on the local filesystem and never transmits to external services, it can safely store file paths, internal URLs, and credential references that would otherwise pose security risks.

How the Lark Kanban Adapter Syncs Evidence

The evidence-projection flow in loopx/extensions/lark/presentation/kanban.py follows a six-step pipeline that guarantees public-safety at every network boundary.

Step 1: Resolving the State File

The sync_loopx_todos_to_lark_kanban() function begins by calling resolve_todo_state_path() to locate the state file under the project's .loopx/ directory. This function accepts an optional custom path but defaults to the standard hidden directory structure (lines 21,726–21,734).

from loopx.extensions.lark.presentation.kanban import (
    resolve_todo_state_path,
    sync_loopx_todos_to_lark_kanban
)

# Resolves to .loopx/todos.json by default

state_path = resolve_todo_state_path(registry_path, goal_id="my-goal")

Step 2: Loading Raw Todos

Once located, the adapter reads the state file and extracts todo blocks for both "user" and "agent" sections. The parsing loop filters out completed items unless the caller explicitly sets include_done=True (lines 21,740–21,766).

Step 3: Public-Safe Transformation

Before any data leaves the local machine, each string field passes through _public_safe_text(). This sanitizer, implemented at lines 21,94–21,104, redacts local file paths, private URLs, internal IDs, and credential references.

The helper _lark_record_from_todo_block() invokes this transformation via _public_safe_lark_values() (lines 21,123–21,128), ensuring the resulting JSON payload contains only public-safe evidence:

from loopx.extensions.lark.presentation.kanban import _public_safe_lark_values

raw_evidence = "See file:///home/user/.ssh/id_rsa for details"
safe_payload = _public_safe_lark_values({"Evidence": raw_evidence})

# Result: {"Evidence": "[local-path-redacted]"}

Step 4: Projecting Issue-Fix Outcomes

The adapter also handles structured issue-fix outcomes generated by the issue_fix capability. The _lark_record_from_projection_block() function transforms these outcomes into Lark rows while again applying the public-safe sanitizer (lines 22,26–22,44 and 21,123–21,128).

Step 5: Writing to Lark

For each sanitized row, the adapter builds a lark-cli record-upsert command via build_record_upsert_command() (lines 21,558–21,574). The command contains the redacted JSON payload, ensuring only public-safe evidence reaches the remote Kanban board. Execution occurs at lines 21,106–21,112, or runs in simulation mode if execute=False.

Step 6: Persisting the Local Mapping

After a successful upsert, the local mapping (record_map) that ties LoopX todo IDs to Lark record IDs writes back into .loopx/ via write_lark_kanban_local_config() (lines 21,336–21,345). This persistence (lines 21,138–21,144) maintains the source of truth locally and enables subsequent incremental syncs without re-creating remote records.

Code Examples

Syncing Todos to Lark

Execute a live sync that reads from .loopx/ and pushes sanitized data to your Lark Kanban board:

from pathlib import Path
from loopx.extensions.lark.presentation.kanban import (
    LarkKanbanConfig,
    default_lark_kanban_config_path,
    sync_loopx_todos_to_lark_kanban,
)

# Load the local Kanban config stored in .loopx

config = LarkKanbanConfig(
    base_token="my_base_token",
    table_id="tbl_12345",
    view_id="vew_kanban",
)

# Sync todos for a specific goal

result = sync_loopx_todos_to_lark_kanban(
    config,
    registry_path=Path.cwd(),
    goal_id="my-goal",
    agent_id="codex-kanban-worker",
    execute=True,  # Actually push to Lark

)

print(f"{result['successful_write_count']} rows written to Lark")

Inspecting the Sanitization

Preview how sensitive data gets redacted before transmission:

from loopx.extensions.lark.presentation.kanban import _public_safe_lark_values

raw_evidence = "Internal server at http://192.168.1.50:8080 failed"
safe_payload = _public_safe_lark_values({"Evidence": raw_evidence})
print(safe_payload["Evidence"])

# Output: "[url-redacted]"

Reading Local Configuration

Access the Kanban configuration stored in your source-of-truth directory:

from pathlib import Path
from loopx.extensions.lark.presentation.kanban import read_lark_kanban_local_config

cfg = read_lark_kanban_local_config(Path(".loopx/lark-kanban.json"))
print(cfg["board"]["base_token"])  # Local copy, never fetched from Lark

Summary

• LoopX treats .loopx/ as the authoritative source of truth for all project state, configurations, and todo mappings.
• The sync_loopx_todos_to_lark_kanban() function in loopx/extensions/lark/presentation/kanban.py orchestrates the projection workflow.
• Every piece of evidence passes through _public_safe_text() before network transmission, redacting file paths, private URLs, and credentials.
• Issue-fix outcomes undergo the same sanitization via _lark_record_from_projection_block().
• Local-to-remote ID mappings persist back into .loopx/ via write_lark_kanban_local_config(), maintaining incremental sync capability while keeping sensitive metadata local.
• The lark-cli integration executes only after sanitization completes, ensuring the Kanban board receives exclusively public-safe evidence.

Frequently Asked Questions

What is the .loopx/ directory used for in LoopX?

The .loopx/ directory serves as the project's hidden source of truth, storing todo state files, Kanban configuration (lark-kanban.json), and local ID mappings. Because it remains on the local filesystem, it safely contains sensitive paths and credentials that should never reach external APIs.

How does LoopX ensure sensitive data isn't exposed to Lark?

LoopX implements a public-safe sanitization layer via _public_safe_text() and _public_safe_lark_values() in kanban.py. These functions intercept all string data before transmission and replace local file paths, private IP addresses, internal URLs, and credential references with redacted tokens like [local-path-redacted].

Can I preview the sanitized data before sending it to Lark?

Yes. Set execute=False when calling sync_loopx_todos_to_lark_kanban() to run in simulation mode. The function will build and log the lark-cli commands without executing them, allowing inspection of the sanitized JSON payloads. You can also call _public_safe_lark_values() directly on your evidence strings to preview the redaction.

Where does LoopX store the mapping between local todos and Lark records?

LoopX persists these mappings in .loopx/lark-kanban.json via the write_lark_kanban_local_config() function. This local storage strategy maintains the association between LoopX internal IDs and remote Lark record IDs, enabling efficient incremental updates without requiring state queries from the Lark API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}