tmd

파일 변환 기능

tmd convert 명령어를 통해 PDF, Office 문서, HTML, 구조화된 데이터 등을 마크다운으로 변환할 수 있습니다. 멀티페이지 PDF의 경우 자동으로 반복되는 페이지 번호를 제거하고, 예산 설정을 통해 헤더/푸터를 지문화하여 제거할 수 있습니다(--keep-boilerplate 옵션으로 비활성화 가능).

클립보드 복사 기능

tmd clip 명령어는 파일을 마크다운으로 변환한 결과를 바로 클립보드에 복사하여 LLM에 바로 붙여넣기 할 수 있도록 합니다.

폴더 감시 기능

tmd watch 명령어는 지정된 폴더를 모니터링하여 새로운 파일이 생성될 때 자동으로 마크다운으로 변환합니다. --budget 옵션과 함께 사용하면 토큰 예산을 기준으로 중복 문단을 제거하고 헤더/푸터를 완전히 stripping할 수 있습니다.

웹 페이지 가져오기 기능

tmd fetch 명령어는 웹 페이지를 가져와 깨끗한 기사 형태의 마크다운으로 저장합니다. 이는 온라인 기사나 문서를 LLM 입력용으로 준비할 때 유용합니다.

저장소 요약 기능

tmd repo 명령어는 전체 코드 저장소를 단일 마크다운 매니페스트로 축소하여 저장소 구조와 내용을 토큰 효율적으로 표현합니다.

문서 병합 기능

tmd merge 명령어는 여러 파일을 하나의 마크다운 문서로 결합하고 자동으로 목차를 생성합니다.

토큰 절감 측정 기능

tmd delta 명령어는 변환 전후의 토큰 수를 비교하여 얼마나 많은 토큰이 절감되었는지 보여줍니다.

다운로드·설치 방법

tokens.md를 사용하기 위해서는 먼저 저장소를 클론하고 Python 3.13+ 및 uv 환경을 설정해야 합니다.

1. 저장소 클론:

git clone https://github.com/intelligent-username/tokens.md

2. uv를 사용한 환경 설정 (권장):

uv sync

3. 수동 가상환경 설정:

python3 -m venv --python=3.13 .venv
# Windows의 경우
.venvScriptsactivate
pip install -e .  # 편집 가능한 설치 (tmd 명령어 제공)

4. 또는 pipx를 사용한 전역 설치 (권장):

pip install pipx
pipx install tokens-md
pipx ensurepath
export PATH="$HOME/.local/bin:$PATH"

기본 사용법/명령어

설치 후 tmd 명령어를 사용할 수 있습니다. 다음은 기본적인 사용 예시입니다.

CLI 사용법

• 현재 폴더의 모든 지원 파일을 변환하여 out/ 폴더에 저장:

tmd convert . --loc="out"

• 여러 개별 파일 변환:

tmd convert 1.pdf 2.docx 3.html -o out/

• 현재 폴더를 현재 디렉토리에 변환:

tmd convert . --loc=.

• 기본 입력/출력 폴더 사용 (input/ → output/):

tmd

• 폴더의 파일을 하나의 문서로 병합:

tmd merge input/ -o output/merged.md

• 웹 페이지 가져오기:

tmd fetch https://example.com/article -o output/article.md

• 저장소를 마크다운 매니페스트로 요약:

tmd repo . -o output/repo.md

• 토큰 절감량 확인:

tmd delta

웹 프론트엔드 사용법

웹 인터페이스를 사용하려면 다음 단계를 따르세요:

1. 웹 의존성 설치:

uv pip install -e ".[web]"

2. 웹 인터페이스 실행:

tmd ui

이 명령어는 백엔드 서버를 http://127.0.0.1:8642에서 실행하고 브라우저를 자동으로 엽니다.

이런 경우에 유용합니다

LLM에 큰 문서나 코드베이스를 입력해야 할 때 토큰 제한으로 인해 잘림 현상이 발생하는 경우, tokens.md를 사용하면 파일 크기를 60~95% 줄여 더 많은 내용을 전달할 수 있습니다. 특히 연구 논문, 기술 매뉴얼, 법적 문서 또는 대규모 코드 저장소를 LLM과 작업해야 하는 전문가들에게 유용합니다. 웹 인터페이스는 드래그 앤 드롭으로 간편하게 파일을 변환하고 결과를 즉시 확인할 수 있어 비개발자도 쉽게 사용할 수 있습니다.

지원 환경·시스템 요구사항

tokens.md는 Windows, Linux, macOS에서 실행할 수 있습니다. Python 3.13 이상과 uv 패키지 관리자가 필요하며, 웹 인터페이스 사용을 위해서는 TypeScript 및 Node.js 환경이 요구됩니다. 저장소 클론 후 uv sync 또는 pip install -e . 명령을 통해 의존성을 설치할 수 있습니다.

최신 버전·업데이트

버전 0.0.18에서는 토큰 예산 기능이 강화되어 더 정밀한 출력 크기 제어가 가능해졌으며, 헤더 및 푸터 제거 로직이 개선되어 변환 결과의 품질이 향상되었습니다. 자세한 변경 사항은 저장소의 커밋 히스토리를 참조하세요.

제한 사항·확인 사항

tokens.md를 사용하기 위해서는 소스 코드를 클론하고 Python 개발 환경을 직접 설정해야 합니다. 바이너리 배포판이나 설치 관리자(.exe, .msi)는 제공되지 않으므로, 개발 도구에 익숙하지 않은 사용자는 설치 과정에서 어려움을 겪을 수 있습니다. 또한 일부 드문 파일 형식이나 특수한 인코딩은 변환 지원이 제한될 수 있습니다.

화면으로 보는 주요 기능

그림 화면

어두운 밤하늘에 빛나는 달과 깊은 그림자 속에서 한 남자가 십자가를 들고 손을 벌리고 있다. 그 주변에는 수많은 사람들이 모여 있으며, 일부는 빛나는 유령처럼 보이고, 다른 이들은 고통스러운 표정을 짓고 있다. 배경에는 폐허가 된 건물과 날아다니는 새들이 보인다.

파일 업로드 및 변환 화면

'tokens.md'라는 웹사이트의 파일 변환 화면이다. 상단에는 'Upload Files or Folders'라는 텍스트와 함께 PDF, Office 문서, 구조화된 데이터, 코드 또는 폴더를 업로드할 수 있는 드래그 앤 드롭 영역이 있다. 중앙에는 두 개의 입력 파일(AtoTC.pptx, AtoTC.docx)이 표시되어 있으며, 각각의 파일은 토큰 수와 압축률을 보여주는 진행률 바를 가지고 있다. 변환된 마크다운 파일(AtoTC.md)은 각각의 입력 파일과 연결되어 있으며, 'Clip', 'Download', 'View' 버튼이 있다. 하단에는 'Settings' 섹션이 있으며, 확장자, 페이지 선택, 토큰 예산 제한, 재귀적 하위 폴더, 헤더 및 푸터 제거 등의 설정 옵션이 있다.