Twill

프로젝트에서 나온 문서와 결정을 한곳에 모아두는 작업 공간.

프로젝트마다 흩어져 있는 기획, 설계, 회의 기록과 할 일을 하나의 문서 공간에서 관리합니다. 실제 프로젝트 폴더를 연결해 두면 문서를 읽고 쓰는 일과 Codex AI 작업도 같은 흐름에서 이어갈 수 있습니다.

옵시디언의 파일 기반 노트, 노션의 데이터베이스와 보드, ChatGPT 데스크톱의 대화 방식에서 영감을 받아 만들었습니다. 문서는 Markdown 파일로 남기고, 프로젝트별 기록과 AI 대화는 필요한 자리에서 바로 찾아 쓸 수 있게 구성했습니다.

주요 기능

기능	설명	화면 자료 제안
프로젝트별 문서 공간	문서 보관 폴더 안에서 프로젝트를 나누고, 각 프로젝트의 실제 작업 디렉토리를 연결합니다. 코드 저장소와 문서 공간은 각자 자리에 두고 함께 열어볼 수 있습니다.	왼쪽에 프로젝트 목록과 문서 트리가 펼쳐지고, 오른쪽에 선택한 문서가 열린 전체 화면
Markdown 문서 편집	글쓰기 화면에서 제목, 목록, 표, 인용, 코드, 이미지와 여러 단 구성 문서를 편집합니다. [[문서 이름]] 링크와 백링크, 태그, 날짜별 노트도 지원합니다.	서식이 적용된 문서와 문서 링크, 옆으로 나뉜 이미지와 텍스트가 함께 보이는 편집 화면
프로젝트 태스크 보드	태스크를 카드로 만들고 보류, 대기, 실행, 확인 필요, 완료 단계로 관리합니다. 카드에서 Codex 작업을 시작하고 실행 기록을 확인할 수 있습니다.	다섯 상태 열과 카드가 보이고, 실행 기록이 포함된 태스크 카드가 열린 보드 화면
Twill AI 채팅	Codex 계정으로 로그인해 대화하고 프로젝트 문서를 바탕으로 작업을 요청합니다. 프로젝트별 AI 작업과 대화 목록은 왼쪽 탐색 영역의 [AI 작업]에 모입니다.	왼쪽 프로젝트 아래 대화 목록과 오른쪽 AI 채팅 내용이 함께 보이는 화면
대화와 문서를 나란히	여러 AI 대화와 문서를 탭으로 열고, 끌어 놓아 화면을 나눕니다. 문서와 대화의 배치 상태는 앱을 다시 열어도 복원됩니다.	한쪽에는 Markdown 문서, 다른 쪽에는 AI 대화가 열린 분할 화면과 위쪽 탭
그림과 다이어그램	문서 공간에서 Mermaid 다이어그램과 ERD를 만들고, 문서에 넣은 이미지에는 사각형·화살표·자유선·텍스트로 주석을 답니다.	흐름도 탭과 주석이 표시된 이미지 문서가 함께 보이는 화면
PDF와 일상 기록	현재 문서를 한글 글꼴과 다이어그램을 포함해 PDF로 내보냅니다. 날짜별 노트, 전체 할 일 보기, 문서 템플릿도 함께 사용할 수 있습니다.	달력에서 날짜를 고르고 해당 날짜의 노트와 할 일을 확인하는 화면
작업 환경 설정	라이트·다크 테마, 터미널, 재사용할 지침을 관리하는 스킬북, 검색과 키보드 단축키를 제공합니다.	설정 창에서 테마를 고르고, 옆에 터미널과 스킬 목록이 보이는 화면

AI 로그인

Twill AI는 Codex CLI를 사용합니다. 앱에서 OpenAI Codex 계정으로 OAuth 로그인하면 Codex 계정의 인증과 사용 한도를 따라 대화와 작업을 실행합니다. 별도의 API 키를 발급하거나 코드 저장소마다 Codex CLI를 설치할 필요가 없습니다.

AI가 프로젝트 문맥을 참고하거나 파일을 수정할 때는 Twill에 연결한 프로젝트 디렉토리를 기준으로 작업합니다. AI를 사용하면 요청과 선택된 문맥이 Codex 서비스로 전송됩니다. Markdown 문서와 첨부 파일은 사용자의 문서 폴더에 저장됩니다.

설치 및 실행

설치 프로그램으로 실행

macOS와 Windows용 설치 프로그램은 각 운영체제에서 빌드할 수 있습니다. 설치형 앱에는 프런트엔드, 백엔드, Codex CLI가 포함되어 있어 Python이나 Node.js를 별도로 설치하지 않아도 됩니다.

저장소에서 실행

처음 실행할 때 Python 3.11 이상, Node.js 22.12 이상과 인터넷 연결이 필요합니다. 설정 스크립트가 백엔드와 프런트엔드 의존성을 준비합니다.

macOS:

./mac/run-desktop.sh

Windows PowerShell:

.\window\run-desktop.bat

브라우저에서 개발하려면 macOS에서는 ./mac/run.sh, Windows에서는 window\run.bat를 실행합니다.

문서와 설정은 어디에 저장되나요?

처음 실행할 때 선택한 문서 폴더가 작업 공간이 됩니다. 설치형 앱의 기본 위치는 다음과 같습니다.

• macOS: ~/Documents/Twill
• Windows: %USERPROFILE%\Documents\Twill

Markdown 노트와 첨부 파일은 이 폴더 안에 보관됩니다. 검색과 문서 연결에 쓰는 색인은 폴더 안의 숨김 데이터로 관리하며, 원본 노트는 일반 Markdown 파일이라 다른 편집기에서도 열 수 있습니다. 앱 설정과 Codex 인증은 문서와 별도로 사용자 계정에 저장됩니다.

개발

Twill은 Electron 데스크톱 화면, React·TypeScript 프런트엔드, Python·FastAPI 백엔드로 구성됩니다. 데스크톱 앱을 실행하면 백엔드가 사용자 컴퓨터에서 로컬로 시작됩니다.

frontend/   Electron 앱과 React 화면
backend/    FastAPI, 파일 인덱싱, 작업 관리, Codex 연결
mac/        macOS 실행·설정·설치 프로그램 스크립트
window/     Windows 실행·설정·설치 프로그램 스크립트

일반적인 개발 실행 방법은 다음과 같습니다.

# 프런트엔드 의존성 설치
cd frontend && npm ci

# 프런트엔드 빌드
npm run build

# Electron 구문 확인과 린트
npm run desktop:check
npm run lint

백엔드 의존성은 저장소 루트에서 OS별 설정 스크립트로 준비할 수 있습니다. 설치 프로그램은 macOS에서 ./mac/build-installer.sh, Windows에서 window\build-installer.bat로 만듭니다.

Mac과 Windows 사이에 소스를 공유할 때는 Git을 사용하세요. node_modules, .venv, dist, build, release는 운영체제별로 다시 생성합니다. 개인 노트 폴더, 사용자 스킬, 환경 변수 파일과 인증서는 저장소에 커밋하지 않습니다.