https://github.com/magicdrive/ark
Yet another alternate [directory | repository] represent text generator tool
https://github.com/magicdrive/ark
ai directory-tree llm summary
Last synced: 2 months ago
JSON representation
Yet another alternate [directory | repository] represent text generator tool
- Host: GitHub
- URL: https://github.com/magicdrive/ark
- Owner: magicdrive
- License: mit
- Created: 2025-06-02T11:58:23.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-19T09:24:37.000Z (3 months ago)
- Last Synced: 2026-03-19T14:25:17.705Z (3 months ago)
- Topics: ai, directory-tree, llm, summary
- Language: Go
- Homepage:
- Size: 219 KB
- Stars: 22
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ark
> Yet another alternate \[directory | repository\] text generator tool
**ark** recursively scans a directory and produces a clean, human‑readable dump of the tree and file contents. Perfect for
* 📚 sharing codebases with LLMs
* 🧪 static‑analysis pipelines
* 🗂️ snapshotting source trees
It supports **plaintext**, **markdown**, **XML**, and **arklite** outputs, full UTF‑8 handling (with optional skip), and extensive filtering.
---
## 🚀 Quick Start
### 1 · Install
### 1. Installation
```bash
go install github.com/magicdrive/ark@latest
```
Using Homebrew:
```bash
brew install magicdrive/tap/ark
```
Or download a pre-built binary from [Releases](https://github.com/magicdrive/ark/releases).
---
### 2 · Generate an output file
```bash
ark # creates ark_output.txt in the cwd
```
---
## 🧰 Basic Usage
```text
ark [OPTIONS]
ark mcp-server [OPTIONS]
```
---
## ⚙️ General Options
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--help` | `-h` | Show help and exit | – |
| `--version` | `-v` | Show version | – |
| `--output-filename ` | `-o` | Name of the output file | `ark_output.txt` |
| `--scan-buffer ` | `-b` | Read buffer size (`10M`, `500K`, …) | `10M` |
| `--output-format ` | `-f` | `txt`, `md`, `xml`, `arklite` | `txt` |
| `--mask-secrets ` | `-m` | Detect & mask secrets | `on` |
| `--allow-gitignore ` | `-a` | Obey `.gitignore` rules | `on` |
| `--additionally-ignorerule ` | `-A` | Extra ignore‑rule file | – |
| `--with-line-number ` | `-n` | Prepend line numbers | `on` |
| `--ignore-dotfile ` | `-d` | Skip dotfiles | `off` |
| `--pattern-regex ` | `-x` | Include paths matching regexp | – |
| `--include-ext ` | `-i` | Include only ext(s) (`go,ts,html`) | – |
| `--exclude-dir-regex ` | `-g` | Exclude dirs matching regexp | – |
| `--exclude-file-regex ` | `-G` | Exclude files matching regexp | – |
| `--exclude-ext ` | `-e` | Exclude ext(s) | – |
| `--exclude-dir ` | `-E` | Exclude dirs by name | – |
| `--compless` | `-c` | Compress result with **arklite** | – |
| `--skip-non-utf8` | `-s` | Ignore non‑UTF‑8 files | – |
| `--silent` | `-S` | Suppress logs / progress | – |
| `--delete-comments` | `-D` | Strip comments (language‑aware) | – |
---
## 🛰 mcp‑server Options
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--root ` | `-r` | Serve directory root | `$PWD` |
| `--type ` | `-t` | HTTP listen port | `stdio` |
| `--http-port ` | `-p` | HTTP listen port | `8522` |
| `--scan-buffer ` | `-b` | Read buffer size (`10M`, `500K`, …) | `10M` |
| `--mask-secrets ` | `-m` | Detect & mask secrets | `on` |
| `--allow-gitignore ` | `-a` | Obey `.gitignore` rules | `on` |
| `--additionally-ignorerule ` | `-A` | Extra ignore‑rule file | – |
| `--ignore-dotfile ` | `-d` | Skip dotfiles | `off` |
| `--pattern-regex ` | `-x` | Include paths matching regexp | – |
| `--include-ext ` | `-i` | Include only ext(s) (`go,ts,html`) | – |
| `--exclude-dir-regex ` | `-g` | Exclude dirs matching regexp | – |
| `--exclude-file-regex ` | `-G` | Exclude files matching regexp | – |
| `--exclude-ext ` | `-e` | Exclude ext(s) | – |
| `--exclude-dir ` | `-E` | Exclude dirs by name | – |
| `--skip-non-utf8` | `-s` | Ignore non‑UTF‑8 files | – |
| `--delete-comments` | `-D` | Strip comments (language‑aware) | – |
---
## 📝 Arguments
| Argument | Description |
|----------|-------------|
| `` | Directory to scan |
| `` | Size string (`10M`, `100K`, …) |
| `` | File extension (`go`, `ts`, `html`) |
| `` | Go `regexp` syntax pattern |
---
## 📦 Output Examples
Plaintext (--output-format txt)
```text
example_project
├── main.go
└── sub
└── sub.txt
=== sub/sub.txt ===
hello world
```
Markdown (--output-format md)
````markdown
# Project Tree
```
example_project
├── main.go
└── sub
└── sub.txt
```
---
# File: sub/sub.txt
```txt
hello world
```
````
XML (--output-format xml)
```xml
example_project
/abs/path/example_project
```
Arklite (--output-format arklite)
```
# Arklite Format: example_project (/abs/path/example_project)
## Directory Tree (JSON)
{"name":"example_project","type":"directory","children":[{"name":"main.go","type":"file"},{"name":"sub","type":"directory","children":[{"name":"sub.txt","type":"file"}]}]}
## File Dump
@main.go
package mainfunc main(){println("hello")}
@sub/sub.txt
hello world
```
---
## 🤔 What is Arklite?
Arklite is a compact single‑line‑per‑file format tuned for LLM token efficiency:
1. Natural‑language header (project + path)
2. JSON directory tree
3. File dump (`@path` + content with `` for newlines)
---
## 🗂 Example `.arkignore`
```gitignore
# VCS
.git/
.hg/
.svn/
# IDEs / editors
.idea/
.vscode/
*.code-workspace
*.sublime-*
```
---
## 🧩 Shell Completions
```sh
# Bash & Zsh
source completions/ark-completion.sh
# Fish
funcsave ark
```
---
## 📎 See Also
* Project home —
## Author
© 2025 Hiroshi IKEGAMI
## License
Released under the [MIT License](LICENSE)