mlx-code 0.0.7__tar.gz → 0.0.8__tar.gz

{mlx_code-0.0.7 → mlx_code-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlx-code
-Version: 0.0.7
+Version: 0.0.8
 Summary: Coding Agent for Mac
 Home-page: https://github.com/JosefAlbers/mlx-code
 Author: J Joe
@@ -13,6 +13,9 @@ Requires-Dist: mlx-lm>=0.31.3
 Requires-Dist: numpy
 Requires-Dist: httpx
 Requires-Dist: pydantic
+Requires-Dist: GitPython
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: tree-sitter-python
 Dynamic: author
 Dynamic: author-email
 Dynamic: description
@@ -34,7 +37,7 @@ Modern coding agents are like luxury apartments: impressive and shiny, but you d
 
 I wanted a [backyard shed](https://poyo.co/note/20260202T150723/) for myself. Something I understand end to end, can break on purpose, and fix without filing a support ticket.
 
-mlx-code is that shed. It’s deliberately minimal, extremely transparent, and designed around one core idea: the feedback [loop](https://www.robert-glaser.de/what-if-iteration-is-all-we-need/) is the thing that matters, not the interface around it. The tighter and faster you can close the loop between intent and output, the better the work gets. Everything else is ceremony. 
+`mlx-code` is that shed. It’s deliberately minimal, extremely transparent, and designed around one core idea: [feedback loop](https://www.robert-glaser.de/what-if-iteration-is-all-we-need/) is the thing that matters, not the interface around it. The tighter and faster you can close the loop between intent and output, the better the work gets. Everything else is ceremony. 
 
 So the terminal stays the interface. Text in, text out. No full-screen TUI fighting your terminal emulator, no proprietary context format, no behavior that shifts between versions. 
 
@@ -42,27 +45,36 @@ So the terminal stays the interface. Text in, text out. No full-screen TUI fight
 
 ## How It Works
 
-mlx-code has two lightweight, loosely coupled pieces:
+`mlx-code` has two lightweight, loosely coupled pieces:
 
-- **main.py**: A clean MLX server for Apple Silicon. It loads quantized models and exposes a standard OpenAI-compatible completions endpoint.
-- **pie.py** — A minimal but powerful agent harness (Python port of Mario Zechner's awesome [pi](https://github.com/badlogic/pi-mono)).
+- [**main.py**](https://github.com/JosefAlbers/mlx-code/blob/main/mlx_code/main.py): LLM server for Apple Silicon. It loads quantized models and exposes a standard OpenAI-compatible completions endpoint.
+- [**pie.py**](https://github.com/JosefAlbers/mlx-code/blob/main/mlx_code/pie.py): Agentic harness based on Mario Zechner's awesome [pi](https://github.com/badlogic/pi-mono)).
+- [**ledger.py**](https://github.com/JosefAlbers/mlx-code/blob/main/mlx_code/ledger.py): Git worktree manager that creates isolated branches and working directories for every agent (and sub‑agen) runs.
 
 The CLI is intentionally boring and familiar:
 
-- `mc` — Local agent (MLX server + pie REPL)
-- `me` — Remote agent (pie REPL against Claude, DeepSeek, Gemini, etc.)
-- `md` — View and filter structured JSON logs
+- `mc`: Local agent (LLM server ± harness)
+- `me`: Harness. Connects to any compatible API (Claude, DeepSeek, Gemini, OpenAI, or local `mc`)
+- `md`: Log viewer
 
-Agentic work lives on a spectrum from tight, synchronous co-driving to loose, asynchronous delegation — the right tool for both ends is a loop that closes quickly, not a UI that abstracts it away. Text streams compose. They pipe. They chain. They work the same way they did thirty years ago and will work thirty years from now. That's the constraint that shapes the whole tool.
+Agentic work lives on a spectrum from tight, synchronous co-driving to loose, asynchronous delegation. The right tool for both ends is a loop that closes quickly, not a UI that abstracts it away. 
+
+Text streams compose. They pipe. They chain. They work the same way they did thirty years ago and will work thirty years from now. 
+
+That's the [constraint](https://jordanlord.co.uk/blog/3-constraints/) that shapes the whole tool.
 
 ## Features
 
-- **Multi-Provider Compatibility**: Translates and handles requests formatted for Claude, Gemini, Codex, and DeepSeek.
-- **Built-in REPL & Tools**: `pie` is a fully-featured REPL with tool execution and reasoning token support.
-- **Prompt Caching**: KV cache is saved to disk and reused across requests automatically.
-- **Server Mode**: Spin up a local LLM server with one command.
+- **Local or remote execution**: Run models locally via MLX or connect to Claude, Gemini, Codex, DeepSeek, or any OpenAI‑compatible endpoint.
+- **Git worktree isolation**: Every agent run (and every sub‑agent) lives in its own git worktree and branch. Changes are automatically snapshotted (`commit_worktree`), and you can `cleanup_worktree` when done. This makes experimentation safe and fully reversible.
+- **Autonomous sub‑agents**: Spawn isolated agents in fresh git worktrees. Each sub‑agent has its own conversation, tool set, and working directory. They can be used for parallel exploration, refactoring, or deep research without polluting the main context.
+- **Symbol‑aware source inspection (`ReadTree`)**: Uses tree‑sitter to outline code or fetch exact definitions/calls for a symbol. Drastically reduces token usage compared to reading full files.
+- **Built‑in tools**: Read, Write, Edit, Bash, Grep, Find, Ls, ReadTree, GetSkill, and Agent.
+- **Prompt caching**: KV cache is saved to disk and reused across requests automatically.
+- **REPL with `/commands`**: `/clear`, `/history`, `/tools`, `/branch`, `/abort`, `/help`.
+- **TUI log viewer (`md`)**: Explore structured JSON logs with filtering by level, file, function, etc. Mark entries to export.
 
-### Quick Start
+## Quick Start
 
 Install via pip and launch the agent immediately:
 
@@ -73,37 +85,37 @@ mc
 
 ## Command Line Interfaces
 
-### `mc` — Local agent (MLX server + harness)
+### `mc`: Local agent (LLM server ± harness)
 
 ```bash
-# Default: starts local MLX server and launches pie REPL
+# Start local MLX server and launch the default pie harness (Default)
 mc
 
-
-# Choose a different harness
+# Choose a different harness (claude, gemini, codex, deepseek, pie)
 mc --leash gemini
 mc --leash codex
 mc --leash claude
-mc --leash pie 
-
-# Use a local model
-mc --model mlx-community/Qwen3.5-4B-OptiQ-4bit
-mc --leash none       # server only, no harness
 
-# Change server address
-mc --host 0.0.0.0 --port 9000
+# Server only, no harness
+mc --leash none
 
-# Limit available tools
+# Limit allowed tools
 mc --tools Ls ReadTree Edit
 
+# Use a custom system prompt
+mc --system "You are a helpful Python expert."
+
+# Load skills from a directory
+mc --skill ./my-skills
+
 # Shell piping and chaining
 echo "explain symgraph.py" | mc -d | cat - PLAN.md | mc
 ```
 
-### `me` — Remote agent (pie REPL against any API)
+### `me`: Harness (connects to API)
 
 ```bash
-# Default: connects to local server at 127.0.0.1:8000
+# Connect to local server at 127.0.0.1:8000 (Default)
 me
 
 # Use a remote provider
@@ -112,33 +124,36 @@ me --api claude
 me --api gemini
 me --api codex
 
-# Use a specific model
-me --api deepseek --model deepseek-chat
+# Specify model
+me --api deepseek --model deepseek-v4-pro
 
-# Point at a custom endpoint
+# Point to a custom LLM API endpoint
 me --url http://localhost:9000
+
+# Load skills from a directory
+me --skill ./my-skills
 ```
 
-### `md` — Log viewer
+### `md`: TUI log viewer
 
 View and filter structured JSON logs from any session.
 
 ```bash
 md
-md --filter lvl:10;file:main,pie
-md --out picks
+md --filter "lvl:10;file:main,pie"    # show DEBUG logs from main.py and pie.py
+md --out picks.json                   # write marked entries to a file
 ```
 
-## Credits
-
-- `main.py`: Built on [mlx](https://github.com/ml-explore/mlx) and [mlx-lm](https://github.com/ml-explore/mlx-lm) by Apple.
-- `pie.py`: Adapted from [pi](https://github.com/badlogic/pi-mono) by Mario Zechner (MIT License).
-
-## Licence
-
-Apache License 2.0 — see LICENSE for details.
+Inside the TUI:
+- `j/k` or ↑/↓ – navigate
+- `o` – open detailed view for current entry
+- `*` – highlight related entries (same file/function)
+- `;` – set a live filter
+- `h/l` – switch between request‑grouped tabs
+- `v` – mark/unmark entry for export
+- `q` – quit (marked entries printed or saved with `--out`)
 
-<details><summary>...</summary><pre>
+<details><summary>Click to expand</summary><pre>
 
 ~/tmp> mc
 
@@ -173,102 +188,6 @@ Apache License 2.0 — see LICENSE for details.
     ≫
     Bye!
 
-~/tmp> gg **/*.py
-
-    staging: mlx_code/__init__.py
-      exists
-    staging: mlx_code/log.py
-      exists
-    staging: mlx_code/main.py
-      exists
-    staging: mlx_code/pie.py
-      exists
-    staging: mlx_code/symgraph.py
-      exists
-    staging: setup.py
-      exists
-
-    Diff preview:
-     mlx_code/__init__.py |    4 +
-     mlx_code/log.py      |  771 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-     mlx_code/main.py     | 1597 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-     mlx_code/pie.py      | 1994 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-     mlx_code/symgraph.py |  483 +++++++++++++++++++++++++++++++++++
-     setup.py             |   18 ++
-     6 files changed, 4867 insertions(+)
-
-    Show per-file diffs? [s=skip]: y
-
-    --- mlx_code/__init__.py ---
-    @@ -0,0 +1,4 @@
-    +from .main import serve, run
-    +from .pie import harness
-    +
-    +__all__ = ["serve", "run", "harness"]
-    --- mlx_code/log.py ---
-    ... (     772 lines total, truncated)
-    +    if args.out:
-    +        with open(args.out, "w", encoding="utf-8") as f:
-    +            for idx in sorted(marked):
-    +                f.write(json.dumps(logs[idx]) + "\n")
-    +    else:
-    +        for idx in sorted(marked):
-    +            print(json.dumps(logs[idx]))
-    +
-    +if __name__ == "__main__":
-    +    main()
-    --- mlx_code/main.py ---
-    ... (    1598 lines total, truncated)
-    +            model=args.model,
-    +            system=system,
-    +            tools=args.tools,
-    +            skill=args.skill,
-    +            leash_args=leash_args,
-    +        )
-    +
-    +if __name__ == "__main__":
-    +    main()
-    +# }}}ser
-    --- mlx_code/pie.py ---
-    ... (    1995 lines total, truncated)
-    +        cwd=args.cwd,
-    +        model=model,
-    +        base_url=url,
-    +        tools=tools,
-    +        sdir=args.skill,
-    +        api_key=api_key
-    +    )
-    +
-    +if __name__ == "__main__":
-    +    main()
-    --- mlx_code/symgraph.py ---
-    ... (     485 lines total, truncated)
-    +       B,H=search_symbols(A.symbols,C,lang_ext=E,include_references=not A.no_references,include_context=A.context,warn_skipped=A.warn_skipped);G=_C
-    +       for(I,J)in H.items():
-    +               if J is Capability.NONE:_warn(f"'{I}': no matching identifiers found (grammar may be unsupported for this file type)");G=_E
-    +       if A.kinds:B=[B for B in B if B.kind in A.kinds]
-    +       if A.json:print(json.dumps([A.as_dict()for A in B],indent=2))
-    +       else:print_usages(B,F)
-    +       if G and not B:return 2
-    +       return 0
-    +if __name__=='__main__':sys.exit(main())
-    
-    --- setup.py ---
-    ... (      19 lines total, truncated)
-    +    version="0.0.7",
-    +    readme="README.md",
-    +    description="Coding Agent for Mac",
-    +    long_description=open("README.md").read(),
-    +    long_description_content_type="text/markdown",
-    +    python_requires=">=3.12.8",
-    +    install_requires=["mlx-lm>=0.31.3", "numpy", "httpx", "pydantic"],
-    +    packages=find_packages(),
-    +    entry_points={"console_scripts": ["mc=mlx_code.main:main", "md=mlx_code.log:main", "me=mlx_code.pie:main"]},
-    +)
-
-    read> v0.0.7
-    Saved snapshot d2ab186ee5c02f0589552ffac658c4f4a284b36c
-
 ~/tmp> mc
 
     pie REPL  •  type /help for commands, Ctrl-D or 'exit' to quit.
@@ -476,7 +395,7 @@ Apache License 2.0 — see LICENSE for details.
 
     The tool is particularly useful for developers who need precise, language-aware code navigation and search capabilities without relying on IDE-specific features.
 
-~/tmp> python log.py -o test
+~/tmp> md -o test
 
     ┌─ logs ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐┌─ detail ──────────────────────────────────────────────────────────────────────────┐
     │ TIME      LVL       FILE              FUNC              MESSAGE                                                            …││ time       : 2026-05-09T17:35:17.021887+00:00                                     │
@@ -606,6 +525,33 @@ Apache License 2.0 — see LICENSE for details.
 
     **Bottom line:** `ReadTree` is a sharp tool for context efficiency — it can slash input size dramatically for tasks like code explanation, and the smaller context window often allows the model to think faster and more focused.
 
-~/tmp[1 jobs]> hx --capture
-
 </pre></details><br>
+
+## Tools Overview
+
+| Tool        | Description |
+|-------------|-------------|
+| `Read`      | Read a file (supports offset/limit for large files). |
+| `Write`     | Create or overwrite a file. |
+| `Edit`      | Replace a unique string in a file. |
+| `Bash`      | Run a shell command (timeout, stdout+stderr). |
+| `Grep`      | Search file contents with regex, respects `.gitignore`. |
+| `Find`      | Find files/directories by name pattern. |
+| `Ls`        | List directory contents (respects `.gitignore`). |
+| `ReadTree`  | Outline a file/directory or fetch exact bodies of definitions/calls. Uses tree‑sitter and works for many languages (Python, JS/TS, Go, Rust, Java, C/C++, C#, Ruby, etc.). |
+| `GetSkill`  | Retrieve full instructions for a named skill (from `--skill` directory). |
+| `Agent`     | Spawn an autonomous sub‑agent in an isolated git worktree. For parallel tasks, deep research, or safe experimentation. |
+
+## Skills
+
+Skills are directories containing a `SKILL.md` file with frontmatter (`name:` and `description:`). Place them in a directory and pass `--skill <dir>`. The agent will list available skills and can load their full instructions via `GetSkill`. This keeps the system prompt lean while allowing on‑demand detailed guidance.
+
+
+## Credits
+
+- `main.py`: Built on [mlx](https://github.com/ml-explore/mlx) and [mlx-lm](https://github.com/ml-explore/mlx-lm) by Apple.
+- `pie.py`: Adapted from [pi](https://github.com/badlogic/pi-mono) by Mario Zechner (MIT License).
+
+## Licence
+
+Apache License 2.0 — see LICENSE for details.

{mlx_code-0.0.7 → mlx_code-0.0.8}/README.md

@@ -8,7 +8,7 @@ Modern coding agents are like luxury apartments: impressive and shiny, but you d
 
 I wanted a [backyard shed](https://poyo.co/note/20260202T150723/) for myself. Something I understand end to end, can break on purpose, and fix without filing a support ticket.
 
-mlx-code is that shed. It’s deliberately minimal, extremely transparent, and designed around one core idea: the feedback [loop](https://www.robert-glaser.de/what-if-iteration-is-all-we-need/) is the thing that matters, not the interface around it. The tighter and faster you can close the loop between intent and output, the better the work gets. Everything else is ceremony. 
+`mlx-code` is that shed. It’s deliberately minimal, extremely transparent, and designed around one core idea: [feedback loop](https://www.robert-glaser.de/what-if-iteration-is-all-we-need/) is the thing that matters, not the interface around it. The tighter and faster you can close the loop between intent and output, the better the work gets. Everything else is ceremony. 
 
 So the terminal stays the interface. Text in, text out. No full-screen TUI fighting your terminal emulator, no proprietary context format, no behavior that shifts between versions. 
 
@@ -16,27 +16,36 @@ So the terminal stays the interface. Text in, text out. No full-screen TUI fight
 
 ## How It Works
 
-mlx-code has two lightweight, loosely coupled pieces:
+`mlx-code` has two lightweight, loosely coupled pieces:
 
-- **main.py**: A clean MLX server for Apple Silicon. It loads quantized models and exposes a standard OpenAI-compatible completions endpoint.
-- **pie.py** — A minimal but powerful agent harness (Python port of Mario Zechner's awesome [pi](https://github.com/badlogic/pi-mono)).
+- [**main.py**](https://github.com/JosefAlbers/mlx-code/blob/main/mlx_code/main.py): LLM server for Apple Silicon. It loads quantized models and exposes a standard OpenAI-compatible completions endpoint.
+- [**pie.py**](https://github.com/JosefAlbers/mlx-code/blob/main/mlx_code/pie.py): Agentic harness based on Mario Zechner's awesome [pi](https://github.com/badlogic/pi-mono)).
+- [**ledger.py**](https://github.com/JosefAlbers/mlx-code/blob/main/mlx_code/ledger.py): Git worktree manager that creates isolated branches and working directories for every agent (and sub‑agen) runs.
 
 The CLI is intentionally boring and familiar:
 
-- `mc` — Local agent (MLX server + pie REPL)
-- `me` — Remote agent (pie REPL against Claude, DeepSeek, Gemini, etc.)
-- `md` — View and filter structured JSON logs
+- `mc`: Local agent (LLM server ± harness)
+- `me`: Harness. Connects to any compatible API (Claude, DeepSeek, Gemini, OpenAI, or local `mc`)
+- `md`: Log viewer
 
-Agentic work lives on a spectrum from tight, synchronous co-driving to loose, asynchronous delegation — the right tool for both ends is a loop that closes quickly, not a UI that abstracts it away. Text streams compose. They pipe. They chain. They work the same way they did thirty years ago and will work thirty years from now. That's the constraint that shapes the whole tool.
+Agentic work lives on a spectrum from tight, synchronous co-driving to loose, asynchronous delegation. The right tool for both ends is a loop that closes quickly, not a UI that abstracts it away. 
+
+Text streams compose. They pipe. They chain. They work the same way they did thirty years ago and will work thirty years from now. 
+
+That's the [constraint](https://jordanlord.co.uk/blog/3-constraints/) that shapes the whole tool.
 
 ## Features
 
-- **Multi-Provider Compatibility**: Translates and handles requests formatted for Claude, Gemini, Codex, and DeepSeek.
-- **Built-in REPL & Tools**: `pie` is a fully-featured REPL with tool execution and reasoning token support.
-- **Prompt Caching**: KV cache is saved to disk and reused across requests automatically.
-- **Server Mode**: Spin up a local LLM server with one command.
+- **Local or remote execution**: Run models locally via MLX or connect to Claude, Gemini, Codex, DeepSeek, or any OpenAI‑compatible endpoint.
+- **Git worktree isolation**: Every agent run (and every sub‑agent) lives in its own git worktree and branch. Changes are automatically snapshotted (`commit_worktree`), and you can `cleanup_worktree` when done. This makes experimentation safe and fully reversible.
+- **Autonomous sub‑agents**: Spawn isolated agents in fresh git worktrees. Each sub‑agent has its own conversation, tool set, and working directory. They can be used for parallel exploration, refactoring, or deep research without polluting the main context.
+- **Symbol‑aware source inspection (`ReadTree`)**: Uses tree‑sitter to outline code or fetch exact definitions/calls for a symbol. Drastically reduces token usage compared to reading full files.
+- **Built‑in tools**: Read, Write, Edit, Bash, Grep, Find, Ls, ReadTree, GetSkill, and Agent.
+- **Prompt caching**: KV cache is saved to disk and reused across requests automatically.
+- **REPL with `/commands`**: `/clear`, `/history`, `/tools`, `/branch`, `/abort`, `/help`.
+- **TUI log viewer (`md`)**: Explore structured JSON logs with filtering by level, file, function, etc. Mark entries to export.
 
-### Quick Start
+## Quick Start
 
 Install via pip and launch the agent immediately:
 
@@ -47,37 +56,37 @@ mc
 
 ## Command Line Interfaces
 
-### `mc` — Local agent (MLX server + harness)
+### `mc`: Local agent (LLM server ± harness)
 
 ```bash
-# Default: starts local MLX server and launches pie REPL
+# Start local MLX server and launch the default pie harness (Default)
 mc
 
-
-# Choose a different harness
+# Choose a different harness (claude, gemini, codex, deepseek, pie)
 mc --leash gemini
 mc --leash codex
 mc --leash claude
-mc --leash pie 
-
-# Use a local model
-mc --model mlx-community/Qwen3.5-4B-OptiQ-4bit
-mc --leash none       # server only, no harness
 
-# Change server address
-mc --host 0.0.0.0 --port 9000
+# Server only, no harness
+mc --leash none
 
-# Limit available tools
+# Limit allowed tools
 mc --tools Ls ReadTree Edit
 
+# Use a custom system prompt
+mc --system "You are a helpful Python expert."
+
+# Load skills from a directory
+mc --skill ./my-skills
+
 # Shell piping and chaining
 echo "explain symgraph.py" | mc -d | cat - PLAN.md | mc
 ```
 
-### `me` — Remote agent (pie REPL against any API)
+### `me`: Harness (connects to API)
 
 ```bash
-# Default: connects to local server at 127.0.0.1:8000
+# Connect to local server at 127.0.0.1:8000 (Default)
 me
 
 # Use a remote provider
@@ -86,33 +95,36 @@ me --api claude
 me --api gemini
 me --api codex
 
-# Use a specific model
-me --api deepseek --model deepseek-chat
+# Specify model
+me --api deepseek --model deepseek-v4-pro
 
-# Point at a custom endpoint
+# Point to a custom LLM API endpoint
 me --url http://localhost:9000
+
+# Load skills from a directory
+me --skill ./my-skills
 ```
 
-### `md` — Log viewer
+### `md`: TUI log viewer
 
 View and filter structured JSON logs from any session.
 
 ```bash
 md
-md --filter lvl:10;file:main,pie
-md --out picks
+md --filter "lvl:10;file:main,pie"    # show DEBUG logs from main.py and pie.py
+md --out picks.json                   # write marked entries to a file
 ```
 
-## Credits
-
-- `main.py`: Built on [mlx](https://github.com/ml-explore/mlx) and [mlx-lm](https://github.com/ml-explore/mlx-lm) by Apple.
-- `pie.py`: Adapted from [pi](https://github.com/badlogic/pi-mono) by Mario Zechner (MIT License).
-
-## Licence
-
-Apache License 2.0 — see LICENSE for details.
+Inside the TUI:
+- `j/k` or ↑/↓ – navigate
+- `o` – open detailed view for current entry
+- `*` – highlight related entries (same file/function)
+- `;` – set a live filter
+- `h/l` – switch between request‑grouped tabs
+- `v` – mark/unmark entry for export
+- `q` – quit (marked entries printed or saved with `--out`)
 
-<details><summary>...</summary><pre>
+<details><summary>Click to expand</summary><pre>
 
 ~/tmp> mc
 
@@ -147,102 +159,6 @@ Apache License 2.0 — see LICENSE for details.
     ≫
     Bye!
 
-~/tmp> gg **/*.py
-
-    staging: mlx_code/__init__.py
-      exists
-    staging: mlx_code/log.py
-      exists
-    staging: mlx_code/main.py
-      exists
-    staging: mlx_code/pie.py
-      exists
-    staging: mlx_code/symgraph.py
-      exists
-    staging: setup.py
-      exists
-
-    Diff preview:
-     mlx_code/__init__.py |    4 +
-     mlx_code/log.py      |  771 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-     mlx_code/main.py     | 1597 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-     mlx_code/pie.py      | 1994 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-     mlx_code/symgraph.py |  483 +++++++++++++++++++++++++++++++++++
-     setup.py             |   18 ++
-     6 files changed, 4867 insertions(+)
-
-    Show per-file diffs? [s=skip]: y
-
-    --- mlx_code/__init__.py ---
-    @@ -0,0 +1,4 @@
-    +from .main import serve, run
-    +from .pie import harness
-    +
-    +__all__ = ["serve", "run", "harness"]
-    --- mlx_code/log.py ---
-    ... (     772 lines total, truncated)
-    +    if args.out:
-    +        with open(args.out, "w", encoding="utf-8") as f:
-    +            for idx in sorted(marked):
-    +                f.write(json.dumps(logs[idx]) + "\n")
-    +    else:
-    +        for idx in sorted(marked):
-    +            print(json.dumps(logs[idx]))
-    +
-    +if __name__ == "__main__":
-    +    main()
-    --- mlx_code/main.py ---
-    ... (    1598 lines total, truncated)
-    +            model=args.model,
-    +            system=system,
-    +            tools=args.tools,
-    +            skill=args.skill,
-    +            leash_args=leash_args,
-    +        )
-    +
-    +if __name__ == "__main__":
-    +    main()
-    +# }}}ser
-    --- mlx_code/pie.py ---
-    ... (    1995 lines total, truncated)
-    +        cwd=args.cwd,
-    +        model=model,
-    +        base_url=url,
-    +        tools=tools,
-    +        sdir=args.skill,
-    +        api_key=api_key
-    +    )
-    +
-    +if __name__ == "__main__":
-    +    main()
-    --- mlx_code/symgraph.py ---
-    ... (     485 lines total, truncated)
-    +       B,H=search_symbols(A.symbols,C,lang_ext=E,include_references=not A.no_references,include_context=A.context,warn_skipped=A.warn_skipped);G=_C
-    +       for(I,J)in H.items():
-    +               if J is Capability.NONE:_warn(f"'{I}': no matching identifiers found (grammar may be unsupported for this file type)");G=_E
-    +       if A.kinds:B=[B for B in B if B.kind in A.kinds]
-    +       if A.json:print(json.dumps([A.as_dict()for A in B],indent=2))
-    +       else:print_usages(B,F)
-    +       if G and not B:return 2
-    +       return 0
-    +if __name__=='__main__':sys.exit(main())
-    
-    --- setup.py ---
-    ... (      19 lines total, truncated)
-    +    version="0.0.7",
-    +    readme="README.md",
-    +    description="Coding Agent for Mac",
-    +    long_description=open("README.md").read(),
-    +    long_description_content_type="text/markdown",
-    +    python_requires=">=3.12.8",
-    +    install_requires=["mlx-lm>=0.31.3", "numpy", "httpx", "pydantic"],
-    +    packages=find_packages(),
-    +    entry_points={"console_scripts": ["mc=mlx_code.main:main", "md=mlx_code.log:main", "me=mlx_code.pie:main"]},
-    +)
-
-    read> v0.0.7
-    Saved snapshot d2ab186ee5c02f0589552ffac658c4f4a284b36c
-
 ~/tmp> mc
 
     pie REPL  •  type /help for commands, Ctrl-D or 'exit' to quit.
@@ -450,7 +366,7 @@ Apache License 2.0 — see LICENSE for details.
 
     The tool is particularly useful for developers who need precise, language-aware code navigation and search capabilities without relying on IDE-specific features.
 
-~/tmp> python log.py -o test
+~/tmp> md -o test
 
     ┌─ logs ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐┌─ detail ──────────────────────────────────────────────────────────────────────────┐
     │ TIME      LVL       FILE              FUNC              MESSAGE                                                            …││ time       : 2026-05-09T17:35:17.021887+00:00                                     │
@@ -580,6 +496,33 @@ Apache License 2.0 — see LICENSE for details.
 
     **Bottom line:** `ReadTree` is a sharp tool for context efficiency — it can slash input size dramatically for tasks like code explanation, and the smaller context window often allows the model to think faster and more focused.
 
-~/tmp[1 jobs]> hx --capture
-
 </pre></details><br>
+
+## Tools Overview
+
+| Tool        | Description |
+|-------------|-------------|
+| `Read`      | Read a file (supports offset/limit for large files). |
+| `Write`     | Create or overwrite a file. |
+| `Edit`      | Replace a unique string in a file. |
+| `Bash`      | Run a shell command (timeout, stdout+stderr). |
+| `Grep`      | Search file contents with regex, respects `.gitignore`. |
+| `Find`      | Find files/directories by name pattern. |
+| `Ls`        | List directory contents (respects `.gitignore`). |
+| `ReadTree`  | Outline a file/directory or fetch exact bodies of definitions/calls. Uses tree‑sitter and works for many languages (Python, JS/TS, Go, Rust, Java, C/C++, C#, Ruby, etc.). |
+| `GetSkill`  | Retrieve full instructions for a named skill (from `--skill` directory). |
+| `Agent`     | Spawn an autonomous sub‑agent in an isolated git worktree. For parallel tasks, deep research, or safe experimentation. |
+
+## Skills
+
+Skills are directories containing a `SKILL.md` file with frontmatter (`name:` and `description:`). Place them in a directory and pass `--skill <dir>`. The agent will list available skills and can load their full instructions via `GetSkill`. This keeps the system prompt lean while allowing on‑demand detailed guidance.
+
+
+## Credits
+
+- `main.py`: Built on [mlx](https://github.com/ml-explore/mlx) and [mlx-lm](https://github.com/ml-explore/mlx-lm) by Apple.
+- `pie.py`: Adapted from [pi](https://github.com/badlogic/pi-mono) by Mario Zechner (MIT License).
+
+## Licence
+
+Apache License 2.0 — see LICENSE for details.