epiq 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/dist/index.js +57 -53
  2. package/dist/mcp.js +51 -48
  3. package/package.json +10 -11
  4. package/readme.md +44 -65
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "epiq",
3
- "version": "0.5.2",
3
+ "version": "0.6.0",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "description": "EPIQ - CLI based issue tracker",
@@ -45,7 +45,9 @@
45
45
  "publish:tarball": "FILE=$(ls -t epiq-*.tgz | head -n 1) && echo \"Publishing $FILE\" && npm publish \"$FILE\"",
46
46
  "release": "pnpm pack:check && pnpm publish:tarball",
47
47
  "start:mcp": "IS_LOCAL=true tsx source/mcp/server.ts",
48
- "inspect:mcp": "pnpm dlx @modelcontextprotocol/inspector"
48
+ "inspect:mcp": "pnpm dlx @modelcontextprotocol/inspector",
49
+ "lint": "eslint .",
50
+ "lint:err": "eslint . --quiet"
49
51
  },
50
52
  "files": [
51
53
  "dist"
@@ -60,29 +62,26 @@
60
62
  "zod": "^4.3.6"
61
63
  },
62
64
  "devDependencies": {
65
+ "@eslint/js": "^10.0.1",
63
66
  "@sindresorhus/tsconfig": "^3.0.1",
64
67
  "@types/marked-terminal": "^6.1.1",
65
68
  "@types/node": "^25.5.0",
66
69
  "@types/react": "^18.0.32",
70
+ "@typescript-eslint/eslint-plugin": "^8.59.2",
71
+ "@typescript-eslint/parser": "^8.59.2",
67
72
  "@vdemedes/prettier-config": "^2.0.1",
68
73
  "@vitest/coverage-v8": "4.1.2",
69
74
  "chalk": "^5.2.0",
70
75
  "esbuild": "^0.25.0",
76
+ "eslint": "^10.3.0",
71
77
  "eslint-plugin-react": "^7.32.2",
72
78
  "eslint-plugin-react-hooks": "^4.6.0",
73
79
  "prettier": "^2.8.7",
74
80
  "ts-node": "^10.9.1",
75
81
  "tsx": "^4.20.3",
76
82
  "typescript": "^5.0.3",
77
- "vitest": "^4.1.0",
78
- "xo": "^0.53.1"
79
- },
80
- "xo": {
81
- "extends": "xo-react",
82
- "prettier": true,
83
- "rules": {
84
- "react/prop-types": "off"
85
- }
83
+ "typescript-eslint": "^8.59.2",
84
+ "vitest": "^4.1.0"
86
85
  },
87
86
  "prettier": "@vdemedes/prettier-config"
88
87
  }
package/readme.md CHANGED
@@ -2,89 +2,59 @@
2
2
 
3
3
  # Epiq
4
4
 
5
- _Distributed CLI based issue tracker TUI_ backed by Git.
5
+ _Distributed terminal-native issue tracker backed by Git._
6
6
 
7
- Issue tracking is a part of the development lifecycle, but it often becomes a painful context switching exercise with poor ergonomics. `Epiq` provides issue tracking as a portable, integrated part of the development environment, with access to all the powerful tooling developers are used to. Epiq allows you to manage all your projects directly via the command line in a visual kanban board and edit content in your favorite editor.
7
+ Issue tracking is a core part of software development, but it often becomes a painful context-switching exercise with poor ergonomics. Epiq provides issue tracking as a portable, integrated part of the development environment, with access to all the powerful tooling developers are used to.
8
8
 
9
- With great attention to user ergonomics, epiq intends to make project management painless and friction free again, and has developer satisfaction as its primary target.
9
+ > You can manage all your projects directly via the command line in a visual kanban board and edit content in your favorite editor.
10
+
11
+ With great attention to user ergonomics and developer experience, epiq makes project management painless and friction free.
10
12
 
11
13
  ```
12
- '███████╗██████╗ ██╗ ██████╗ '
13
- '██╔════╝██╔══██╗██║██╔═══██╗'
14
- '█████╗ ██████╔╝██║██║ ██║'
15
- '██╔══╝ ██╔═══╝ ██║██║▄▄ ██║'
16
- '███████╗██║ ██║╚██████╔╝'
17
- '╚══════╝╚═╝ ╚═╝ ╚═══▀▀╝ '
18
- 🫡 Never leave your editor!
14
+ ███████╗██████╗ █ █╗ ██████╗
15
+ ██╔════╝██╔══██╗█ █║██╔═══██╗
16
+ █████╗ ██████╔╝█ █║██║ ██║
17
+ ██╔══╝ ██╔═══╝ █ █║██║▄▄ ██║
18
+ ███████╗██║ █ █║╚██████╔╝
19
+ ╚══════╝╚═╝ ╚══╝ ╚═══▀▀╝
20
+ 🫡 Never leave your terminal!
19
21
  ```
20
22
 
21
23
  ## What is epiq?
22
24
 
23
- Epiq is a vim-inspired issue tracker fully integrated in the terminal that brings the tooling to the developers’ fingertips - in their comfort zone.
24
-
25
- Epiq renders your issue board directly in the terminal using ASCII and stores its state as an event log, versioned and synchronized through Git.
25
+ Epiq is a vim-inspired issue tracker that brings project management into the terminal. It renders directly in ASCII and persists state as an immutable distributed event log, versioned and synchronized through Git.
26
26
 
27
- ![Epiq cli kanban view](https://raw.Githubusercontent.com/ljtn/epiq/main/assets/overview.png)
28
- ![Epiq cli log view](https://raw.Githubusercontent.com/ljtn/epiq/main/assets/log.png)
27
+ ![Epiq cli kanban view](https://raw.githubusercontent.com/ljtn/epiq/main/assets/overview.png)
28
+ ![Epiq cli log view](https://raw.githubusercontent.com/ljtn/epiq/main/assets/log.png)
29
29
 
30
30
  ## Features
31
31
 
32
32
  - Issue tracking — track work in tickets with name, description, tags, assignees, history log, etc.
33
33
  - Ergonomics — fast keyboard-driven UX, command line with history, syntax highlighting etc.
34
+ - Command palette — press `?` to open a scrollable overview of all available commands and descriptions
34
35
  - Time travel — inspect your app 1h, 1 week or 1 year ago
35
36
  - Filtering — query issues by description, tags, assignees, etc.
36
- - Autocompletion — minimize typing, stay in flow
37
+ - Autocompletion — minimize typing, stay in flow, reuse previous commands
37
38
  - Multi-user — collaborative synchronization via Git
38
39
  - Traceable event log — state is a full history of every change ever made
40
+ - MCP integration - Model Context Protocol support for agent interaction
39
41
 
40
42
  ## Why epiq?
41
43
 
42
- Most issue trackers live outside your workflow. Epiq brings issue tracking into your editor and your repo—where you already work.
44
+ Most issue trackers live outside your workflow. Epiq brings issue tracking where you already work.
43
45
 
44
46
  These design choices result in a system that is:
45
47
 
46
48
  - **Simple setup** — no accounts, SaaS, or external services required
47
49
  - **Repo-native** — your issues can live where your code lives
48
- - **Offline-friendly** — works anywhere, with eventual consistency as a promise
50
+ - **Offline-friendly** — works anywhere, with eventual consistency
49
51
  - **Speed** — local first, and eventual consistency makes epiq edits instant
50
52
  - **Portable** — run on your local machine, on a remote Linux server or your grandma’s connected toaster
51
53
  - **Command driven** — scriptable and automation-friendly, ready for the agentic era
52
- - **Versioned** — every change is tracked and recoverable through Git
53
-
54
- ---
55
-
56
- ## MCP & Agent Compatibility
57
-
58
- Epiq provides a MCP (Model Context Protocol) server for agents to interact with, making it easy to plug into modern agent frameworks.
59
-
60
- To register Epiq with MCP-compatible clients (e.g. Claude Desktop), add it as a server using the `epiq-mcp` binary. Example configuration:
61
-
62
- ```json
63
- {
64
- "mcpServers": {
65
- "epiq": {
66
- "command": "epiq-mcp"
67
- }
68
- }
69
- }
70
- ```
71
-
72
- Once registered, agents can interact with your local Epiq instance through the MCP.
54
+ - **Versioned** — changes are tracked and recoverable through Git
73
55
 
74
56
  ---
75
57
 
76
- ### Example workflow:
77
-
78
- An issue lifecycle as epiq commands:
79
-
80
- ```
81
- 1. epiq new issue "Fix login bug"
82
- 2. epiq assign @john
83
- 3. epiq tag urgent
84
- 4. # move with keys to reflect progress
85
- 5. epiq close
86
- ```
87
-
88
58
  ## Installation
89
59
 
90
60
  Install globally via npm:
@@ -129,16 +99,15 @@ That’s it!
129
99
  >
130
100
  > - Project definition in `./.epiq/project.json`
131
101
  > - Authoritative Git state at `~/.epiq-global/worktrees/<id>`
132
- > - Local cache in `./.epiq/events/` (ignored by Git)
133
- > - Update your `.Gitignore` to ignore local-only directories (`.epiq/events/`, `.epiq/log/`)
134
-
135
- > Epiq manages a dedicated Git state branch and worktree automatically as the source of truth for synchronization
102
+ > - Updates your `.gitignore` to ignore local-only `.epiq/log/`
103
+ > Epiq manages a dedicated Git state branch and worktree automatically as the source of truth for synchronization.
136
104
 
137
105
  ## Usage Guide
138
106
 
139
107
  ### Help
140
108
 
141
109
  - The first thing to know is that you always can access help with `:help`.
110
+ - Press `?` anytime to open the command palette with all available commands and descriptions.
142
111
 
143
112
  ### Navigation
144
113
 
@@ -178,19 +147,29 @@ Clear all filters with `:filter clear`
178
147
 
179
148
  ---
180
149
 
181
- ## How epiq is synchronized
150
+ ## MCP & Agent Compatibility
182
151
 
183
- Epiq separates state into:
152
+ Epiq provides a MCP (Model Context Protocol) server for agents to interact with, making it easy to plug into modern agent frameworks.
184
153
 
185
- - **Source of truth** - Git state branch
186
- - **Local cache** - `.epiq/events/`
154
+ To register Epiq with MCP-compatible clients (e.g. Claude Desktop), add it as a server using the `epiq-mcp` binary. Example configuration:
187
155
 
188
- Epiq uses Git in the background - no manual Git commands are required. Running `:sync` pulls and pushes changes between your local state and the remote state.
156
+ ```json
157
+ {
158
+ "mcpServers": {
159
+ "epiq": {
160
+ "command": "epiq-mcp"
161
+ }
162
+ }
163
+ }
164
+ ```
165
+
166
+ Once registered, agents can interact with your local Epiq instance through the MCP.
167
+
168
+ ---
169
+
170
+ ## How epiq is synchronized
189
171
 
190
- - Your issue data is stored in a dedicated branch managed automatically by epiq
191
- - A `.epiq/` folder is created in your project:
192
- - `project.json` stores project metadata
193
- - `events/` is a local cache of synchronized event logs (ignored by Git)
172
+ Epiq uses Git in the background - no manual Git commands are required. Running `:sync` synchronizes changes between your local state (persisted at `~/.epiq-global/worktrees/<id>/`) and the remote state. By utilizing Git worktrees, synchronization stays isolated from your regular development workflow. Project tracking metadata is stored in `.epiq/project.json`.
194
173
 
195
174
  ## Conflict Avoidance & Data Integrity
196
175
 
@@ -235,4 +214,4 @@ Epiq follows a **local-first** model:
235
214
 
236
215
  ---
237
216
 
238
- 🫡 Never leave your editor!
217
+ 🫡 Never leave your terminal!