Skip to content

refactor(kiloclaw): replace Linear CLI with Linear MCP server #1635

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
evanjacobson merged 7 commits into from
Mar 27, 2026
+145 −234
Merged

refactor(kiloclaw): replace Linear CLI with Linear MCP server #1635

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
432f2fd
chore(kiloclaw): remove Linear CLI from Dockerfiles
evanjacobson Mar 26, 2026
3878f20
refactor(kiloclaw): replace Linear CLI with Linear MCP in bootstrap
evanjacobson Mar 26, 2026
edac005
feat(kiloclaw): add Linear MCP server to mcporter config
evanjacobson Mar 26, 2026
b9f6bbf
Small tweak to Linear bootstrap
evanjacobson Mar 26, 2026
5ee5389
Final tweak to Linear's bootstrap content
evanjacobson Mar 27, 2026
c1f3cee
Flip baseUrl --> url
evanjacobson Mar 27, 2026
d33284e
Flip baseUrl to url in test as well
evanjacobson Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 2 additions & 7 deletions kiloclaw/Dockerfile
View file
Open in desktop
Copy link
Copy Markdown
Contributor Author

@evanjacobson evanjacobson Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For both Dockerfiles — restores the other PR's change

Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ RUN apt-get update \
| gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg \
&& apt-get update \
&& apt-get install -y --no-install-recommends gh 1password-cli \
&& apt-get purge -y xz-utils \
&& apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/* \
&& node --version \
&& npm --version
Expand All @@ -55,13 +57,6 @@ RUN npm install -g @steipete/summarize@0.12.0
# Install Kilo CLI (agentic coding assistant for the terminal)
RUN npm install -g @kilocode/cli@7.0.46

# Install Linear CLI (issue tracker)
RUN npm install -g @schpet/linear-cli@1.11.1

# Clean up xz-utils now that Node.js and linear-cli are installed
RUN apt-get purge -y xz-utils \
&& apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/*

# Install Go (available at runtime for users to `go install` additional tools)
ENV GO_VERSION=1.26.0
Expand Down
10 changes: 2 additions & 8 deletions kiloclaw/Dockerfile.local
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ RUN apt-get update \
| gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg \
&& apt-get update \
&& apt-get install -y --no-install-recommends gh 1password-cli=2.32.1-1 \
&& apt-get purge -y xz-utils \
&& apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/* \
&& node --version \
&& npm --version
Expand All @@ -56,14 +58,6 @@ RUN npm install -g mcporter@0.7.3
# Install summarize (web page summarization CLI)
RUN npm install -g @steipete/summarize@0.11.1

# Install Linear CLI (issue tracker)
RUN npm install -g @schpet/linear-cli@1.11.1

# Clean up xz-utils now that Node.js and linear-cli are installed
RUN apt-get purge -y xz-utils \
&& apt-get autoremove -y \
&& rm -rf /var/lib/apt/lists/*

# Install Go (available at runtime for users to `go install` additional tools)
ENV GO_VERSION=1.26.0
RUN ARCH="$(dpkg --print-architecture)" \
Expand Down
160 changes: 12 additions & 148 deletions kiloclaw/controller/src/bootstrap.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -494,174 +494,38 @@ describe('configureGitHub', () => {
describe('configureLinear', () => {
it('logs configured when LINEAR_API_KEY is set', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const { deps } = fakeDeps();
const env: Record<string, string | undefined> = {
LINEAR_API_KEY: 'lin_api_test123',
};

configureLinear(env, deps);
configureLinear(env);

expect(env.LINEAR_API_KEY).toBe('lin_api_test123');
expect(logSpy).toHaveBeenCalledWith('Linear CLI configured via LINEAR_API_KEY');
expect(logSpy).toHaveBeenCalledWith('Linear MCP configured via LINEAR_API_KEY');
logSpy.mockRestore();
});

it('removes persisted config directory when no LINEAR_API_KEY', () => {
it('cleans up empty LINEAR_API_KEY and logs not configured', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const { deps, execCalls } = fakeDeps();
const env: Record<string, string | undefined> = {};
const env: Record<string, string | undefined> = {
LINEAR_API_KEY: '',
};

configureLinear(env, deps);
configureLinear(env);

expect(env.LINEAR_API_KEY).toBeUndefined();
expect(execCalls).toContainEqual({
cmd: 'rm',
args: ['-rf', '/root/.config/linear'],
input: undefined,
});
expect(execCalls).toContainEqual({
cmd: 'rm',
args: ['-f', '/root/.linear.toml'],
input: undefined,
});
expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
logSpy.mockRestore();
});

it('still removes ~/.linear.toml when /root/.config/linear removal fails', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const { deps } = fakeDeps();
const env: Record<string, string | undefined> = {};

// Make the first rm call throw, second should still succeed
const origExec = deps.execFileSync;
deps.execFileSync = vi.fn(
(cmd: string, args: string[], opts?: Parameters<BootstrapDeps['execFileSync']>[2]) => {
if (cmd === 'rm' && args.includes('/root/.config/linear')) {
throw new Error('permission denied');
}
return origExec(cmd, args, opts);
}
) as typeof deps.execFileSync;

configureLinear(env, deps);

expect(warnSpy).toHaveBeenCalledWith(
'WARNING: failed to remove /root/.config/linear: permission denied'
);
// Second rm should still have been attempted
expect(deps.execFileSync).toHaveBeenCalledWith('rm', ['-f', '/root/.linear.toml'], {
stdio: 'pipe',
});
logSpy.mockRestore();
warnSpy.mockRestore();
});

it('warns when /root/.config/linear removal fails', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const { deps } = fakeDeps();
const env: Record<string, string | undefined> = {};

const origExec = deps.execFileSync;
deps.execFileSync = vi.fn(
(cmd: string, args: string[], opts?: Parameters<BootstrapDeps['execFileSync']>[2]) => {
if (cmd === 'rm' && args.includes('/root/.config/linear')) {
throw new Error('permission denied');
}
return origExec(cmd, args, opts);
}
) as typeof deps.execFileSync;

configureLinear(env, deps);

expect(warnSpy).toHaveBeenCalledWith(
'WARNING: failed to remove /root/.config/linear: permission denied'
);
expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
logSpy.mockRestore();
warnSpy.mockRestore();
});

it('warns when ~/.linear.toml removal fails', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const { deps } = fakeDeps();
const env: Record<string, string | undefined> = {};

const origExec = deps.execFileSync;
deps.execFileSync = vi.fn(
(cmd: string, args: string[], opts?: Parameters<BootstrapDeps['execFileSync']>[2]) => {
if (cmd === 'rm' && args.includes('/root/.linear.toml')) {
throw new Error('read-only filesystem');
}
return origExec(cmd, args, opts);
}
) as typeof deps.execFileSync;

configureLinear(env, deps);

expect(warnSpy).toHaveBeenCalledWith(
'WARNING: failed to remove /root/.linear.toml: read-only filesystem'
);
expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
logSpy.mockRestore();
warnSpy.mockRestore();
});

it('warns for both when both rm calls fail', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const { deps } = fakeDeps();
const env: Record<string, string | undefined> = {};

deps.execFileSync = vi.fn((cmd: string) => {
if (cmd === 'rm') throw new Error('disk full');
return '';
}) as typeof deps.execFileSync;

configureLinear(env, deps);

expect(warnSpy).toHaveBeenCalledWith(
'WARNING: failed to remove /root/.config/linear: disk full'
);
expect(warnSpy).toHaveBeenCalledWith('WARNING: failed to remove /root/.linear.toml: disk full');
expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
expect(logSpy).toHaveBeenCalledWith('Linear: not configured');
logSpy.mockRestore();
warnSpy.mockRestore();
});

it('formats non-Error thrown values in warning', () => {
it('logs not configured when LINEAR_API_KEY is absent', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const { deps } = fakeDeps();
const env: Record<string, string | undefined> = {};

deps.execFileSync = vi.fn((cmd: string) => {
if (cmd === 'rm') throw 'unexpected string error';
return '';
}) as typeof deps.execFileSync;

configureLinear(env, deps);

expect(warnSpy).toHaveBeenCalledWith(
'WARNING: failed to remove /root/.config/linear: unexpected string error'
);
logSpy.mockRestore();
warnSpy.mockRestore();
});

it('cleans up empty LINEAR_API_KEY', () => {
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const { deps } = fakeDeps();
const env: Record<string, string | undefined> = {
LINEAR_API_KEY: '',
};

configureLinear(env, deps);
configureLinear(env);

expect(env.LINEAR_API_KEY).toBeUndefined();
expect(logSpy).toHaveBeenCalledWith('Linear: not configured');
logSpy.mockRestore();
});
});
Expand Down Expand Up @@ -878,7 +742,7 @@ describe('updateToolsMdLinearSection', () => {

expect(harness.writeCalls).toHaveLength(1);
expect(harness.writeCalls[0]!.data).toContain('<!-- BEGIN:linear -->');
expect(harness.writeCalls[0]!.data).toContain('linear issue list');
expect(harness.writeCalls[0]!.data).toContain('Linear MCP');
expect(harness.writeCalls[0]!.data).toContain('<!-- END:linear -->');
});

Expand Down
83 changes: 12 additions & 71 deletions kiloclaw/controller/src/bootstrap.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,44 +327,17 @@ export function configureGitHub(env: EnvLike, deps: BootstrapDeps = defaultDeps)
// ---- Step 6: Linear config ----

/**
* Configure or clean up Linear CLI access.
* When LINEAR_API_KEY is present the CLI reads it natively.
* When absent, clean up any on-disk credentials left by a previous
* `linear auth login --plaintext` on the persistent volume.
* Best-effort: logs warnings on failure, does not throw.
*
* The CLI stores two files under ~/.config/linear/:
* - credentials.toml — workspace list + inline API keys (plaintext mode)
* - linear.toml — global config that can also carry an api_key field
* It may also create ~/.linear.toml (a project-level or legacy config file).
* The system keyring is not available in this container (no libsecret-tools),
* so these files are the only persistence locations.
* Configure or clean up Linear MCP access.
* Linear access is provided via the Linear MCP server configured in mcporter.
* When LINEAR_API_KEY is present, mcporter uses it to authenticate.
* When absent, we just clean up the env var. No on-disk artifacts to clean.
*/
export function configureLinear(env: EnvLike, deps: BootstrapDeps = defaultDeps): void {
export function configureLinear(env: EnvLike): void {
if (env.LINEAR_API_KEY) {
console.log('Linear CLI configured via LINEAR_API_KEY');
console.log('Linear MCP configured via LINEAR_API_KEY');
} else {
// Clean up env var if explicitly set to empty
delete env.LINEAR_API_KEY;
// Remove any previously stored credentials from the persistent volume.
// The CLI recreates ~/.config/linear/ via ensureDir on next auth login.
// rm -rf/-f exit 0 when the target is absent, so errors here are
// genuine failures (permissions, I/O) worth surfacing.
try {
deps.execFileSync('rm', ['-rf', '/root/.config/linear'], { stdio: 'pipe' });
} catch (err) {
console.warn(
`WARNING: failed to remove /root/.config/linear: ${err instanceof Error ? err.message : err}`
);
}
try {
deps.execFileSync('rm', ['-f', '/root/.linear.toml'], { stdio: 'pipe' });
} catch (err) {
console.warn(
`WARNING: failed to remove /root/.linear.toml: ${err instanceof Error ? err.message : err}`
);
}
console.log('Linear: not configured (credentials cleared)');
console.log('Linear: not configured');
}
}

Expand Down Expand Up @@ -590,50 +563,18 @@ const LINEAR_MARKER_END = '<!-- END:linear -->';

const LINEAR_TOOLS_SECTION = `
${LINEAR_MARKER_BEGIN}
## Linear

The \`linear\` CLI is configured with your Linear API key. Use it to read and manage issues.

- Run \`linear --help\` for full command reference; \`--help\` after any subcommand for details.
- If you don't know the team key, run \`linear team list\`.

### Listing issues

Example — list all issues by priority:
\`\`\`
linear issue list --team <key> --sort priority --all-states --all-assignees
\`\`\`

**Flags that silently filter results when omitted:**
- \`--state\` defaults to \`backlog\`. Use \`--all-states\` for all, or \`--state <value>\` to filter to one: triage, backlog, unstarted, started, completed, canceled
- \`--assignee\` defaults to \`me\`. Use \`--all-assignees\` for all, or \`--assignee <user>\` to filter to one

### Writing issue content
Use file flags for markdown with newlines or special characters:
- \`--description-file <path>\` for \`issue create/update\`
- \`--body-file <path>\` for \`comment add/update\`

### Config file
Avoid repeated \`--team\` and \`--sort\` flags with \`.linear.toml\` in the project directory:
\`\`\`toml
team = "TEAM_KEY"
sort = "priority"
\`\`\`
## Linear

### Gotchas
- \`--no-pager\` only works on \`issue list\` — errors on other commands
- GraphQL non-null types (\`String!\`) require heredoc: \`linear api --variable key=val <<'GRAPHQL'\`
Linear is configured as your project management tool. Use it to track issues, plan projects, and manage product roadmaps.
You can interact with the \`Linear\` MCP server using your \`mcporter\` skill.

### Advanced
- Get API token: \`linear auth token\`
- Direct GraphQL: \`curl -s -X POST https://api.linear.app/graphql -H "Authorization: $(linear auth token)" -d '{"query":"..."}'\`
${LINEAR_MARKER_END}`;

/**
* Manage the Linear section in TOOLS.md.
*
* When LINEAR_API_KEY is present, append a bounded section so the agent
* knows the linear CLI is available. When absent, remove any stale section.
* knows Linear MCP is available. When absent, remove any stale section.
* Idempotent: skips if the marker is already present.
*/
export function updateToolsMdLinearSection(env: EnvLike, deps: BootstrapDeps): void {
Expand Down Expand Up @@ -718,7 +659,7 @@ export async function bootstrap(
await yieldToEventLoop();

setPhase('linear');
configureLinear(env, deps);
configureLinear(env);
await yieldToEventLoop();

const configExists = deps.existsSync(CONFIG_PATH);
Expand Down
Loading
Loading