# ahmetb/kubectx architecture

> Architecture diagram of the GitHub repository ahmetb/kubectx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmetb/kubectx
- Repository: https://github.com/ahmetb/kubectx

## Overview

kubectx and kubens are command-line tools for managing the active Kubernetes context and namespace. Users invoke a command to inspect or change kubeconfig settings; kubens can also query namespaces from the active cluster. kubectx additionally supports context rename/delete, interactive selection, and isolated or read-only shells. The graph follows documented capabilities and sampled entry points; some command-to-helper wiring is inferred from the file layout, so uncertain internal calls are omitted.

Main entry points: [`internal/kubeconfig/kubeconfigloader.go`](https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/kubeconfigloader.go) (Load kubeconfig), [`cmd/kubectx/main.go`](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/main.go) (kubectx CLI), [`cmd/kubectx/shell_session.go`](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/shell_session.go) (Shell session), [`cmd/kubens/main.go`](https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/main.go) (kubens CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ctx["kubectx"]
  node_ctxcli["kubectx CLI<br/>[main.go]"]
  node_ctxswitch["Switch context<br/>[switch.go]"]
  node_ctxlist["List contexts<br/>[list.go]"]
  node_ctxrename["Rename context<br/>[rename.go]"]
  node_ctxdelete["Delete context<br/>[delete.go]"]
  node_ctxcurrent["Show context<br/>[current.go]"]
  node_ctxfzf["Context picker<br/>[fzf.go]"]
end

subgraph group_ns["kubens"]
  node_nscli["kubens CLI<br/>[main.go]"]
  node_nsswitch["Switch namespace<br/>[switch.go]"]
  node_nslist["List namespaces<br/>[list.go]"]
  node_nscurrent["Show namespace<br/>[current.go]"]
  node_nsfzf["Namespace picker<br/>[fzf.go]"]
end

subgraph group_core["Kubeconfig core"]
  node_kcloader["Load kubeconfig"]
  node_kccontexts["Context access<br/>[contexts.go]"]
  node_kcmodify["Context updates<br/>[contextmodify.go]"]
  node_kcnamespace["Namespace access<br/>[namespace.go]"]
  node_kccurrent["Current context<br/>[currentcontext.go]"]
end

subgraph group_shell["Shell modes"]
  node_shellsession["Shell session<br/>[shell_session.go]"]
  node_readonly["Read-only proxy<br/>[readonly.go]"]
end

node_user(("User"))
node_kstore["Kubeconfig files"]
node_shellcmd(("Interactive shell"))
node_cluster{{"Kubernetes API"}}
node_fzf(("fzf"))

node_user -->|"invokes"| node_ctxcli
node_user -->|"invokes"| node_nscli
node_ctxcli -->|"dispatches"| node_ctxswitch
node_ctxcli -->|"dispatches"| node_ctxlist
node_ctxcli -->|"dispatches"| node_ctxrename
node_ctxcli -->|"dispatches"| node_ctxdelete
node_ctxcli -->|"dispatches"| node_ctxcurrent
node_ctxcli -->|"dispatches"| node_ctxfzf
node_ctxcli -->|"starts shell"| node_shellsession
node_nscli -->|"dispatches"| node_nsswitch
node_nscli -->|"dispatches"| node_nslist
node_nscli -->|"dispatches"| node_nscurrent
node_nscli -->|"dispatches"| node_nsfzf
node_ctxswitch -->|"loads config"| node_kcloader
node_ctxswitch -->|"updates context"| node_kcmodify
node_ctxlist -->|"loads config"| node_kcloader
node_ctxlist -->|"reads contexts"| node_kccontexts
node_ctxrename -->|"loads config"| node_kcloader
node_ctxrename -->|"renames context"| node_kcmodify
node_ctxdelete -->|"loads config"| node_kcloader
node_ctxdelete -->|"deletes context"| node_kcmodify
node_ctxcurrent -->|"loads config"| node_kcloader
node_ctxcurrent -->|"reads current"| node_kccurrent
node_ctxfzf -.->|"runs picker"| node_fzf
node_nslist -->|"loads config"| node_kcloader
node_nslist -->|"reads context"| node_kccurrent
node_nslist -->|"reads namespace"| node_kcnamespace
node_nslist -->|"queries namespaces"| node_cluster
node_nsswitch -->|"loads config"| node_kcloader
node_nsswitch -->|"updates namespace"| node_kcnamespace
node_nscurrent -->|"loads config"| node_kcloader
node_nscurrent -->|"reads namespace"| node_kcnamespace
node_nsfzf -.->|"runs picker"| node_fzf
node_shellsession -->|"loads config"| node_kcloader
node_shellsession -->|"checks context"| node_kccontexts
node_shellsession -->|"reads current"| node_kccurrent
node_shellsession -->|"launches"| node_shellcmd
node_shellsession -.->|"configures proxy"| node_readonly
node_shellcmd -->|"uses isolated config"| node_kstore
node_readonly -->|"proxies allowed requests"| node_cluster
node_kcloader -->|"reads config"| node_kstore
node_kcmodify -->|"writes config"| node_kstore

click node_ctxcli "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/main.go"
click node_ctxswitch "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/switch.go"
click node_ctxlist "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/list.go"
click node_ctxrename "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/rename.go"
click node_ctxdelete "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/delete.go"
click node_ctxcurrent "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/current.go"
click node_ctxfzf "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/fzf.go"
click node_nscli "https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/main.go"
click node_nsswitch "https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/switch.go"
click node_nslist "https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/list.go"
click node_nscurrent "https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/current.go"
click node_nsfzf "https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/fzf.go"
click node_kcloader "https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/kubeconfigloader.go"
click node_kccontexts "https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/contexts.go"
click node_kcmodify "https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/contextmodify.go"
click node_kcnamespace "https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/namespace.go"
click node_kccurrent "https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/currentcontext.go"
click node_shellsession "https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/shell_session.go"
click node_readonly "https://github.com/ahmetb/kubectx/blob/master/internal/proxy/readonly.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ctxcli,node_ctxswitch,node_ctxlist,node_ctxrename,node_ctxdelete,node_ctxcurrent,node_ctxfzf,node_user toneBlue
class node_nscli,node_nsswitch,node_nslist,node_nscurrent,node_nsfzf toneAmber
class node_kcloader,node_kccontexts,node_kcmodify,node_kcnamespace,node_kccurrent,node_cluster toneMint
class node_shellsession,node_readonly toneRose
class node_kstore,node_shellcmd,node_fzf toneIndigo
```

## Components

### kubectx

- [kubectx CLI](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/main.go): `cmd/kubectx/main.go`
- [Switch context](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/switch.go): `cmd/kubectx/switch.go`
- [List contexts](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/list.go): `cmd/kubectx/list.go`
- [Rename context](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/rename.go): `cmd/kubectx/rename.go`
- [Delete context](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/delete.go): `cmd/kubectx/delete.go`
- [Show context](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/current.go): `cmd/kubectx/current.go`
- [Context picker](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/fzf.go): `cmd/kubectx/fzf.go`

### kubens

- [kubens CLI](https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/main.go): `cmd/kubens/main.go`
- [Switch namespace](https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/switch.go): `cmd/kubens/switch.go`
- [List namespaces](https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/list.go): `cmd/kubens/list.go`
- [Show namespace](https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/current.go): `cmd/kubens/current.go`
- [Namespace picker](https://github.com/ahmetb/kubectx/blob/master/cmd/kubens/fzf.go): `cmd/kubens/fzf.go`

### Kubeconfig core

- [Load kubeconfig](https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/kubeconfigloader.go): `internal/kubeconfig/kubeconfigloader.go`
- [Context access](https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/contexts.go): `internal/kubeconfig/contexts.go`
- [Context updates](https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/contextmodify.go): `internal/kubeconfig/contextmodify.go`
- [Namespace access](https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/namespace.go): `internal/kubeconfig/namespace.go`
- [Current context](https://github.com/ahmetb/kubectx/blob/master/internal/kubeconfig/currentcontext.go): `internal/kubeconfig/currentcontext.go`

### Shell modes

- [Shell session](https://github.com/ahmetb/kubectx/blob/master/cmd/kubectx/shell_session.go): `cmd/kubectx/shell_session.go`
- [Read-only proxy](https://github.com/ahmetb/kubectx/blob/master/internal/proxy/readonly.go): `internal/proxy/readonly.go`

### Other components

- **User**
- **Kubeconfig files**
- **Interactive shell**
- **Kubernetes API**
- **fzf**

## Connections

- User → kubectx CLI: invokes
- User → kubens CLI: invokes
- kubectx CLI → Switch context: dispatches
- kubectx CLI → List contexts: dispatches
- kubectx CLI → Rename context: dispatches
- kubectx CLI → Delete context: dispatches
- kubectx CLI → Show context: dispatches
- kubectx CLI → Context picker: dispatches
- kubectx CLI → Shell session: starts shell
- kubens CLI → Switch namespace: dispatches
- kubens CLI → List namespaces: dispatches
- kubens CLI → Show namespace: dispatches
- kubens CLI → Namespace picker: dispatches
- Switch context → Load kubeconfig: loads config
- Switch context → Context updates: updates context
- List contexts → Load kubeconfig: loads config
- List contexts → Context access: reads contexts
- Rename context → Load kubeconfig: loads config
- Rename context → Context updates: renames context
- Delete context → Load kubeconfig: loads config
- Delete context → Context updates: deletes context
- Show context → Load kubeconfig: loads config
- Show context → Current context: reads current
- Context picker → fzf: runs picker
- List namespaces → Load kubeconfig: loads config
- List namespaces → Current context: reads context
- List namespaces → Namespace access: reads namespace
- List namespaces → Kubernetes API: queries namespaces
- Switch namespace → Load kubeconfig: loads config
- Switch namespace → Namespace access: updates namespace
- Show namespace → Load kubeconfig: loads config
- Show namespace → Namespace access: reads namespace
- Namespace picker → fzf: runs picker
- Shell session → Load kubeconfig: loads config
- Shell session → Context access: checks context
- Shell session → Current context: reads current
- Shell session → Interactive shell: launches
- Shell session → Read-only proxy: configures proxy
- Interactive shell → Kubeconfig files: uses isolated config
- Read-only proxy → Kubernetes API: proxies allowed requests
- Load kubeconfig → Kubeconfig files: reads config
- Context updates → Kubeconfig files: writes config