orkmode/AGENTS.md

Agent Guidelines

Instructions for AI agents working on orkmode.

Project Context

Orkmode is a native org-mode implementation: Rust parser/core + Qt/QML UI.

Current state: v0.1 — parser and CLI complete, no UI yet.

Codebase Structure

crates/
├── org-ast/        # AST types (Document, Section, Element, etc.)
├── org-parser/     # Tree-sitter parser, AST conversion
├── orkmode-core/   # High-level API, C FFI
└── ork-cli/        # CLI tool (bin name: ork)

Working with the Code

Build

cargo build --release

Requires: Rust 1.70+, C compiler (for tree-sitter grammar).

Test

cargo test

CLI

The ork CLI operates on directories by default:

ork info .                    # Aggregate info for all .org files
ork sections --todos-only     # List TODOs across files
ork query "tag:work" -R       # Recursive search
ork get "section-id" -j       # JSON output
ork toggle "task-id" -n       # Dry run
ork add "New Task" file.org --todo TODO

Use -j/--json for machine-readable output. Use -n/--dry-run for mutations.

Architecture Decisions

Parser

• Uses tree-sitter-org grammar (git submodule)
• Pinned to tree-sitter 0.22 (0.23+ requires rustc 1.90+)
• Conversion in org-parser/src/convert.rs maps tree-sitter nodes to AST

AST

• Follows org-element spec
• All nodes have Span for source locations
• Document → Section* → Element* / Section*
• Inline objects (bold, links) are partially implemented

FFI

• C-compatible FFI in orkmode-core/src/ffi.rs
• Functions prefixed ork_*
• Caller owns returned strings (free with ork_string_free)

Conventions

Rust

• Edition 2021
• Use thiserror for error types
• Use serde for serialization
• Prefer &str over String in function signatures
• Match existing code style

Commits

• Imperative mood: "Add feature" not "Added feature"
• Reference issue/context in body if relevant

CLI

• Commands operate on paths (file or directory)
• Default to current directory
• -R for recursive
• -j for JSON output
• -n for dry run

Current Limitations

1. Inline objects incomplete — tree-sitter-org doesn't fully parse bold/italic/links
2. Property/tag write commands — stubs only, not implemented
3. Timestamp text — displays "set" placeholder, not actual date
4. No incremental parsing — full reparse on every call

Next Steps (v0.2)

Priority: Qt/QML read-only document viewer.

Tasks:

1. Set up Qt6/QML project in ui/
2. Link orkmode-core via C FFI
3. Implement document model (QAbstractItemModel)
4. Basic headline rendering with folding
5. Syntax highlighting

Testing Changes

Before committing:

cargo build --release
cargo test
./target/release/ork check .
./target/release/ork info test.org -j

Questions?

Check VISION.md for project goals and design principles.