mira-transplier 1.0.2

LLM context transpiler that builds a synced .mira workspace view for codebases.

mira-transplier

mira-transplier turns a script or repository into a synced .mira view that is easier for coding agents and LLMs to navigate with less noise.

What the build writes

When you run mira on a folder, it generates a .mira directory with:

• project.mira for the compact file tree and public command surface
• GUIDE.txt for public commands plus admin commands
• per-file chunk metadata, skeletons, and indexes
• history baselines and runtime state for edits and managed terminals

The tool keeps source and .mira in sync, supports history and restore, and works with regular code files, metadata-only document files, and adaptive generic chunking for unsupported text formats such as .java.

Install

pip install mira-transplier

Basic usage

Build the .mira view for the current folder:

mira .

Build a different folder:

mira path/to/project

Run a command from inside a built workspace:

mira !project
mira !structure
mira !list
mira !create file src/stack.py "class Stack:\n    pass"
mira !expand 12_3
mira !edit_after 12_3 "new lines"

If inline text is omitted and stdin is piped, the piped text is read automatically.

You only need to run mira . once per workspace. After that, source edits, chunk edits, creates, deletes, comments, and environment changes sync back into .mira automatically.

Later syncs only reparse touched source files, keep stable file IDs, and rewrite only the generated .mira artifacts whose content actually changed.

Main command groups

• project navigation: !project, !structure, !explore, !expand, !find_line, !search
• file operations: !create, !delete, !move, !copy, !paste
• edits: !edit, !edit_after, !edit_before, !delete_chunk
• workspace metadata: !memory, !goals, descriptions, chunk comments
• managed terminals: !terminals, !terminal

Admin commands

Admin commands stay in .mira/GUIDE.txt and are hidden from the public command surface.

• !index, !index add <path>, !index remove <path>
• !environment [path|clear|create <name>]
• !diff <file_id|path>, !history <file_id|path>, !restore <file_id|path> <version>
• !tool_wrapper [reset|call <prefix> <suffix>|response <prefix> <suffix>]

!environment lists detected virtual environments in the workspace by checking for activation scripts in Scripts. !environment create <name> creates a new virtual environment directly in the workspace root and configures it immediately. You can also configure a custom environment root with a full absolute path. Once configured, project.mira shows the selected environment as:

ENVIRONMENT: .venv (C:\path\to\workspace\.venv)

Chunk comments

Chunk comments are metadata, not source code. They appear in skeleton structure lines and stay attached when the commented chunk keeps the same code but moves to a different chunk ID.

• !add_comment <chunk_id> [text]
• !edit_comment <chunk_id> [text]
• !delete_comment <chunk_id>

When a commented chunk is edited and its code changes, MIRA prompts to update the comment. When edited or inserted chunks do not have a comment yet, MIRA can prompt to add one.

Generic chunking

Unsupported code-like text files use adaptive generic chunking.

• target chunk size: 100 lines
• minimum preferred size before cutting early: 80 lines
• hard maximum when no blank boundary exists: 500 lines
• chunk boundaries prefer blank lines, and can extend up to 50 extra lines to land on a double-blank boundary
• blank separator lines stay at the end of the previous chunk so the next chunk does not begin with empty lines

Notes

• use exactly one command inside each tool call; do not chain multiple commands in a single tool_call
• folder indexing is shallow: subfolders need their own index entry
• dotfiles are ignored by default except .gitignore
• !create accepts inline file content after the target path when creating a file
• file targets accept file IDs, workspace-relative paths, and absolute workspace paths inside the workspace
• create, delete, move, copy, and paste accept relative paths, leading-slash paths, and absolute workspace paths inside the workspace
• !copy only accepts files; folder copy attempts are rejected explicitly
• wrapped placeholder labels such as <file_id|path>, <chunk_id>, and [text] are ignored when they appear before the real argument
• wrapped text payloads such as [...], <...>, "...", '...', and triple-quoted wrappers are unwrapped before file edits when they are clearly acting as outer wrappers
• files with parser errors stay explorable through generic fallback chunking instead of disappearing from the index
• !explore rejects folders explicitly and points back to file paths instead of guessed file IDs
• whole-file edits show a before/after preview, warn above 400 lines, and are blocked above 1000 lines; use !explore <path> for chunked edits on large files
• confirmations accept wrapped y/n answers such as [y], "y", yes, and no, and reject anything else with a clear retry message
• selectors ignore surrounding <>, [], and matching quotes, and chunk ranges ignore extra spaces around -

Requirements

• Python 3.10+
• Windows is the primary tested target right now