coder / coder/claudecode.nvim

[FEATURE] Multiple Named Terminal Layout Configurations

Open
#139 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Lua
Stars
3.1k
Forks
216
PR merge metrics
No merged PRs in 30d

Description

## Problem / Use Case

Currently, claudecode.nvim only supports a single terminal layout configuration. Users who want to interact with Claude Code in different contexts (e.g., floating window for quick queries, side split for longer sessions) must either:

1. Reconfigure and reload the plugin to change layouts
2. Create multiple independent Claude instances (which breaks the single conversation flow)
3. Manually manipulate windows after opening

This limitation makes it difficult to have flexible workflow patterns while maintaining a single Claude conversation instance.

## Proposed Solution

Support **multiple named terminal layout configurations** accessible via Lua API, allowing layout selection to be completely separate from Claude CLI arguments.

### Configuration Example

```lua
{
"coder/claudecode.nvim",
opts = {
terminal = {
-- Define multiple named configurations
configurations = {
float = {
snacks_win_opts = {
position = "float",
width = 0.8,
height = 0.8,
border = "rounded",
}
},
split = {
snacks_win_opts = {
position = "right",
width = 0.4,
border = "rounded",
}
},
drawer = {
snacks_win_opts = {
position = "bottom",
height = 0.3,
border = "single",
}
}
},
-- Optional: specify default configuration
default = "float" -- used when no layout is specified
},
},
}
```

### Lua API Usage

```lua
-- Open Claude with specific layout and arguments
require("claudecode").open({
layout = "split",
args = "--dangerously-skip-permissions --continue"
})

-- Or just layout (uses default args)
require("claudecode").open({ layout = "float" })

-- Or just args (uses default layout)
require("claudecode").open({ args = "--continue" })

-- Focus with layout preference (switch to different layout)
require("claudecode").focus({ layout = "drawer" })
```

### Keymap Examples

```lua
-- Floating window for quick access
vim.keymap.set({ "n", "i", "v", "t" }, "", function()
require("claudecode").open({
layout = "float",
args = "--dangerously-skip-permissions --continue"
})
end, { desc = "Claude (floating)" })

-- Split for focused work
vim.keymap.set({ "n", "i", "v", "t" }, "", function()
require("claudecode").open({
layout = "split",
args = "--dangerously-skip-permissions --continue"
})
end, { desc = "Claude (split)" })

-- Drawer for context checking
vim.keymap.set("n", "ad", function()
require("claudecode").open({
layout = "drawer",
args = "--continue"
})
end, { desc = "Claude (drawer)" })
```

### Command Compatibility

The existing `:ClaudeCode` command should continue to work unchanged, using the default layout:

```vim
" Uses default layout configuration
:ClaudeCode --continue
:ClaudeCode --dangerously-skip-permissions
```

## Benefits

1. **Single Instance**: All layouts reference the same Claude conversation and WebSocket server
2. **Declarative**: Layout configurations defined once, reused everywhere
3. **No CLI Conflicts**: Layout selection completely separate from Claude CLI arguments
4. **Flexible Workflows**: Different layouts for different contexts without reconfiguration
5. **Backward Compatible**: Existing configurations continue to work
6. **Clean API**: Simple, predictable Lua interface
7. **Composable**: Easy to build complex keymaps and commands on top

## Backward Compatibility

For backward compatibility, both configuration styles should be supported:

```lua
-- Old style (still works, becomes the default configuration)
terminal = {
snacks_win_opts = { position = "float", ... }
}

-- New style (opt-in for multiple configurations)
terminal = {
configurations = {
float = { snacks_win_opts = { ... } },
split = { snacks_win_opts = { ... } }
},
default = "float"
}
```

If `configurations` is not specified, the plugin behaves exactly as it does today.

## Implementation Notes

- The same Claude CLI process and WebSocket server instance should be reused across all layouts
- When switching layouts, the terminal buffer could be moved to a new window with the requested layout
- The `layout` parameter should be optional; if omitted, use the `default` configuration
- Invalid layout names should fall back to the default configuration with a warning

## Alternative Considered

Using command-line arguments like `:ClaudeCode split --continue` was considered but rejected because it would conflict with Claude CLI's native argument parsing and create an antipattern of mixing layout concerns with CLI flags.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.